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

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

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

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

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

[2024-09-30.acacia](https://docs.stripe.com/changelog/acacia.md#2024-09-30.acacia) より前のすべての API バージョンには、互換性に関わる変更が含まれます。

2024-09-30.acacia リリース以降、Stripe は[新しい API リリースプロセス](https://stripe.com/blog/introducing-stripes-new-api-release-process)に従って、互換性に関わる変更のない新しい API バージョンを毎月リリースします。年に 2 回、互換性に関わる変更を含む API バージョンから始まる新しいメジャーリリース ([Basil](https://docs.stripe.com/changelog/basil.md) など) が提供されます。月次リリースは、コードを更新することなく安全にアップグレードできます。新しいメジャーリリースにアップグレードする際には、既存の実装の変更が必要な場合があります。

実装に変更を加えることなく、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 エンドポイントを作成したら、これを無効にします。これは次のステップで再度有効にできます。
![2 つのエンドポイントのうち、旧バージョンのみでイベントを送信](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png)

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

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

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

次に、前のステップで作成した新しい Webhook エンドポイントを有効にします。この時点で、すべてのイベントが 2 回送信されます (古い API バージョンで 1 回、新しいバージョンで 1 回)。
![2 つのエンドポイントからのイベント送信と、旧バージョンのみの処理](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png)

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

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

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

- クエリパラメーターが以前のバージョンのものである場合は、イベントを無視します。Stripe がイベントを自動的に再試行できるように、400 ステータスを返すことを推奨します。これにより、元に戻す必要がある場合に、イベントが古い Webhook エンドポイントに再送信されます。
- クエリパラメーターが新しいバージョンのものである場合は、それを処理します。
![2 つのエンドポイントからイベントを送信 (新バージョンのみ処理)](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png)

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

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

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

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

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

古い Webhook エンドポイントを無効にした後、`400` を返したイベントは再配信されません。
![2 つのエンドポイントのうち、新バージョンのみでイベントを送信](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png)