Webhook のバージョン管理を処理する

Webhook エンドポイントの API バージョンをアップグレードする方法をご紹介します。

Webhook エンドポイントでは、特定の API バージョンを設定するか、Stripe アカウントのデフォルトの API バージョンを使用します。静的言語の SDK (.NET、Java、Go) を使用してイベントを処理する場合、Webhook の API バージョンは SDK の生成に使用されたバージョンと一致している必要があります。これらのバージョンが一致していると、イベントオブジェクトの逆シリアル化が正常に実行されます。

このガイドを使用して、対応処理が必要な変更が行われている可能性がある新しい API バージョンに Webhook エンドポイントを問題なくアップグレードしてください。

新しい API バージョンで対応処理が必要な変更が行われるかどうかを確認する

2024-09-30.acacia より前のすべての API バージョンには、破壊的変更があります。

2024-09-30.acacia リリース以降、Stripe は新しい API リリースプロセスに従い、破壊的変更なしで新しい API バージョンを毎月リリースします。年に 2 回、破壊的変更を含む API バージョンで始まる新しいリリース (Acacia など) を発行します。Webhook エンドポイントは、統合を変更することなく、同じリリースの任意の API バージョンに安全にアップグレードできます。

無効になった新しい Webhook エンドポイントを作成する

以下のパラメーターを使用して、新しい Webhook エンドポイントを作成します。

url: 元の Webhook エンドポイントと同じ URL ですが、クエリパラメーターを追加して、2 つの異なるエンドポイントに送信されたイベントを区別します。例: https://example.com/webhooks?version=2024-04-10。
enabled_events: 元の Webhook エンドポイントと同じイベント。
api_version: アップグレード後の API バージョン。最新の API バージョンにアップグレードする場合は、ダッシュボードまたは API を使用してエンドポイントを作成できます。他のバージョンの場合は、 API を使用して特定のバージョンを設定します。

新しい Webhook エンドポイントを作成したら、これを無効にします。これは次のステップで再度有効にできます。

Webhook コードを更新して新しいエンドポイントに送信されたイベントを無視する

イベント処理コードを更新します。

クエリパラメーターが以前の API バージョンのものである場合は、通常どおりに処理します。
クエリパラメーターが新しい API バージョンのものである場合、イベントを無視して 200 のレスポンスを返し、配信の再試行を防ぎます。

次に、前のステップで作成した新しい Webhook エンドポイントを有効にします。この時点で、すべてのイベントが 2 回送信されます(古い API バージョンで 1 回、新しいバージョンで 1 回)。

Webhook コードを更新して新しいエンドポイントのイベントを処理する

使用している Stripe ライブラリのバージョンを更新して、新しい Webhook エンドポイントのバージョンと一致するようにします。変更ログを確認して、対応処理が必要な変更を行うようにしてください。

イベント処理コードを更新します。

クエリパラメーターが以前のバージョンのものである場合は、イベントを無視します。 Stripe がイベントを自動的に再試行できるように、400 ステータスを返すことをお勧めします。これにより、元に戻す必要がある場合に、イベントが古い Webhook エンドポイントに再送信されます。
クエリパラメーターが新しいバージョンのものである場合は、それを処理します。

新しい Webhook エンドポイントを監視する

新しいコードでイベントが正しく処理されない場合には、以下を試してください。

コードを以前のバージョンに戻します。
新しい Webhook エンドポイントを一時的に無効にします。
失敗したイベントを処理します (前のステップで説明したように 400 ステータスを返した場合、 Stripe はすべてのイベントを自動的に再送信します)。
問題を調査して修正します。
新しい Webhook エンドポイントを有効にして、モニタリングを再開します。

古い Webhook エンドポイントを無効にする

アップグレードが成功したら、古い Webhook エンドポイントを無効にして、サーバーが 400 ステータスを返さないようにします。無効にしないと、200 レスポンスに依存するシステムで問題が発生する可能性があります。

古い Webhook エンドポイントを無効にすると、Stripe は 400 を返したイベントを再配信しません。