Webhook エンドポイントで Stripe イベントを受信する
Webhook エンドポイントの Stripe アカウントでイベントをリッスンし、実装で自動的にリアクションをトリガーできるようにします。
AWS アカウントにイベントを送信する
イベントの送信先に Amazon EventBridge を指定してイベントを直接送信できるようになりました。
Stripe のシステムを構築する際、自社のアプリが Stripe アカウントで発生するイベントを受信できるようにすることをお勧めします。こうすることで、バックエンドシステムは適宜アクションを実行できます。
HTTPS Webhook エンドポイントでイベントを受信するためのイベントの送信先を作成します。Webhook エンドポイントを登録すると、Stripe は、Stripe アカウントで Event (イベント) が発生した際に、リアルタイムのイベントデータをアプリの Webhook エンドポイントにプッシュできます。Stripe は、HTTPS を使用して、Event オブジェクトを含む JSON ペイロードとして Webhook イベントをアプリに送信します。
Webhook イベントの受信は、顧客の銀行が支払いを確定したとき、顧客が支払いに対して不審請求を申請したとき、継続支払いが成功したとき、サブスクリプションの支払いを回収するときなど、非同期イベントをリッスンする際に特に便利です。
イベントの送信先を指定して Amazon EventBridge でイベントを受信することもできます。
始める
アプリで Webhook イベントの受信を開始するには、以下のようにします。
- Webhook エンドポイントハンドラを作成して、イベントデータの POST リクエストを受信します。
- Stripe CLI を使用して、ローカルで Webhook エンドポイントハンドラをテストします。
- Webhook エンドポイントに新しいイベントの送信先を作成します。
- Webhook エンドポイントを保護します。
1 つのエンドポイントを登録、作成して、複数のイベントタイプを同時に処理するか、特定のイベントに個別のエンドポイントを設定することができます。
ハンドラを作成する
POST メソッドを使用して、Webhook リクエストの受け付けが可能な HTTP または HTTPS エンドポイント関数を設定します。ローカルマシンでエンドポイント関数を開発中の場合、HTTP を使用できます。公開アクセスが可能になったら、Webhook エンドポイント関数は HTTPS を使用する必要があります。
エンドポイント関数を設定し、以下を行うようにします。
- Event オブジェクトで構成される JSON ペイロードを使用して、POST リクエストを処理します。
- タイムアウトを引き起こす可能性のある複雑なロジックの前に、成功のステータスコード (
2xx
) を素早く返します。たとえば、会計システムで顧客の請求書を支払い済みとして更新する前に、200
のレスポンスを返す必要があります。
注
別の方法として、インタラクティブな Webhook エンドポイントビルダーを使用し、ご使用のプログラム言語で Webhook エンドポイント関数を構築することもできます。
エンドポイントの例
このコードスニペットは、イベントタイプが受信されたことを確認し、イベントを処理して、コード 200 のレスポンスを返すよう設定された Webhook 関数です。
ハンドラをテストする
Webhook エンドポイント関数を本番環境に移行する前に、アプリケーションの連携をテストすることをお勧めします。これを行うには、自身のローカルマシンにイベントを送信するようローカスリスナーを設定し、テストイベントを送信します。テストには、CLI を使用する必要があります。
ローカルエンドポイントにイベントを転送する
ローカルエンドポイントにイベントを転送するには、CLI で以下のコマンドを実行し、ローカルリスナーを設定します。--forward-to
フラグは、テスト環境のすべての Stripe イベントをローカルの Webhook エンドポイントに送信します。
stripe listen --forward-to localhost:4242/webhook
注
Stripe Shell でStripe リッスンコマンドを実行して、Stripe Shell 端末からイベントを確認することもできますが、Shell からローカルエンドポイントにイベントを転送することはできません。
ローカルリスナーでのテストに役立つ便利な設定として、以下のようなものがあります。
- HTTPS 証明書の検証を無効にするには、
--skip-verify
のオプションフラグを使用します。 - 特定のイベントのみを転送するには、
--events
のオプションフラグを使用して、カンマで区切ったイベントのリストを渡します。
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \ --forward-to localhost:4242/webhook
- Stripe に登録済みの公開 Webhook エンドポイントからローカルの Webhook エンドポイントにイベントを転送するには、
--load-from-webhooks-api
のオプションフラグを使用します。これにより、登録されたエンドポイントにイベントが読み込まれ、パスとその登録イベントが解析され、そのパスが--forward-to path
のローカルの Webhook エンドポイントに関連付けられます。
stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook
- Webhook の署名を確認するには、リッスンコマンドの初期出力から
{{WEBHOOK_
を使用します。SIGNING_ SECRET}}
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
テストイベントをトリガーする
テストイベントを送信するには、Stripe ダッシュボードでオブジェクトを手動で作成し、Webhook が登録されているイベントタイプをトリガーします。あるいは、Stripe Shell または Stripe CLI で次のコマンドを使用できます。
この例では、payment_
イベントをトリガーします。
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Stripe for VS Code を使用してイベントをトリガーする方法をご確認ください。
エンドポイントを登録する
Webhook エンドポイント関数をテストしたら、Workbench の API または Webhook タブで Webhook エンドポイントがアクセス可能な URL を登録し、イベントの送信先を Stripe が認識していることを確認します。Stripe では最大 16 個の Webhook エンドポイントを登録できます。登録される Webhook エンドポイントは、パブリックアクセス可能な HTTPS URL である必要があります。
Webhook の URL 形式
Webhook エンドポイントを登録するための URL 形式は、次のとおりです。
https://<your-website>/<your-webhook-endpoint>
たとえば、ドメインが https://mycompanysite.
で、Webhook エンドポイントへのルートが @app.
の場合、エンドポイント URL には https://mycompanysite.
を指定します。
Webhook エンドポイントのイベント送信先を作成する
ダッシュボードのワークベンチを使用するか、API を使用してプログラムでイベントの送信先を作成します。Stripe アカウントごとに最大 16 のイベントの送信先を登録できます。
注
既存の開発者ダッシュボードはワークベンチに置き換えられます。開発者ダッシュボードを引き続き使用している場合は、新しい Webhook エンドポイントを作成する方法をご覧ください。
エンドポイントを保護する
ハンドラですべての Webhook リクエストが Stripe によって生成されたものであることを確認して、実装を保護する必要があります。公式ライブラリを使用して Webhook の署名を検証するか、手動で検証できます。
Webhook との連携のデバッグを行う
Webhook エンドポイントにイベントを送信する際に、以下のような複数のタイプの問題が発生することがあります。
- Stripe が Webhook エンドポイントにイベントを送信できない可能性がある
- Webhook エンドポイントで SSL の問題が発生している可能性がある
- ネットワーク接続が断続的である
- Webhook エンドポイントが、受信する予定のイベントを受信していない
イベントの送信を表示する
イベント配信を表示するには、Webhook で Webhook エンドポイントを選択し、イベントタブを選択します。
イベントタブには、イベントのリストと、各イベントが Delivered
、Pending
、Failed
のいずれであるかが表示されます。イベントをクリックして、Delivery attempts
を表示すると、以前行われた配信の試行の HTTP ステータスコードや、保留中になっているイベントの今後の配信時刻が示されます。

Webhook エンドポイントのイベントタブで、イベント送信の試行を表示します。
HTTP ステータスコードを修正する
イベントにステータスコード 200
が表示されている場合は、Webhook エンドポイントへの送信が成功したことを示しています。200
以外のステータスコードを受信する場合もあります。次の表で、一般的な HTTP ステータスコードと推奨される解決方法の一覧をご覧ください。
保留中の Webhook ステータス | 説明 | 修正 |
---|---|---|
(接続不可) ERR | 宛先サーバーへの接続を確立できません。 | ホストドメインがインターネットで一般に公開されアクセス可能であることを確認します。 |
(302 ) ERR (またはその他の 3xx ステータス) | 宛先サーバーがリクエストを別の場所にリダイレクトしようとしました。Webhook リクエストへのリダイレクト応答は失敗と見なされます。 | Webhook エンドポイントの送信先を、リダイレクトによって解決される URL に設定します。 |
(400 ) ERR (またはその他の 4xx ステータス) | 宛先サーバーがリクエストを処理できないか、処理しません。これは、サーバーがエラーを検出した場合 (400 )、宛先 URL にアクセス制限が設定されている場合 (401 、403 )、または宛先 URL が存在しない (404 ) 場合に発生することがあります。 |
|
(500 ) ERR (またはその他の 5xx ステータス) | リクエストの処理中に、宛先サーバーでエラーが発生しました。 | アプリケーションのログを確認して、500 エラーが返されている理由を調べます。 |
(TLS エラー) ERR | 宛先サーバーへの安全な接続を確立できませんでした。これらのエラーは通常、宛先サーバーの証明書チェーン内の SSL/TLS 証明書または中間証明書の問題によって発生します。Stripe では、TLS バージョン v1.2 以降が必要です。 | SSL サーバーテストを実行して、このエラーの原因となった可能性がある問題を見つけます。 |
(タイムアウト) ERR | 宛先サーバーで Webhook リクエストに応答するのに時間がかかりすぎました。 | Webhook 処理コードで複雑なロジックを延期して、成功を示すレスポンスを即時に返すようにしてください。 |
イベント送信の動作
このセクションは、Stripe が Webhook エンドポイントにイベントを送信する際に想定されるさまざまな動作を理解するのに役立ちます。
自動での再試行
本番環境では、Stripe は指数バックオフを使用して最長 3 日間、送信先へのイベントの配信を試行します。イベント送信先のイベントの配信タブで、該当がある場合、次回の再試行のタイミングを確認します。Stripe はサンドボックスで作成されたイベントの配信を数時間のうちに 3 回再試行します。Stripe が再試行するときに、送信先が無効化または削除されていた場合、そのイベントの以降の再試行は行われません。ただし、Stripe が再試行できるようになる前にイベントの送信先を無効にして、再び有効にした場合は、以降の再試行が引き続き行われます。
手動での再試行
Unsupported for Amazon EventBridge
You can’t manually resend events to Amazon EventBridge.
There are two ways to manually retry events:
- In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
- With the Stripe CLI, run the
stripe events resend <event_
command. This works for up to 30 days after the event creation.id> --webhook-endpoint=<endpoint_ id>
イベントの順序付け
Stripe は、イベントが生成された順序で配信されることを保証しません。たとえば、サブスクリプションを作成することで、次のイベントが生成されるとします。
customer.
subscription. created invoice.
created invoice.
paid charge.
(支払いが付随する場合)created
イベントの送信先が、特定の順序でのイベントの受信に左右されないようにしてください。配送を適切に管理できるように準備します。API を使用して不足しているオブジェクトを取得することもできます。たとえば、最初に受信したイベントが invoice.
であった場合は、それに含まれる情報を使用して請求書、支払い、サブスクリプションの各オブジェクトを取得できます。
API のバージョン管理
イベント発生時のアカウント設定内の API バージョンによって、API バージョンが指定され、それにより送信先に送られる Event (イベント) の構造が決定されます。たとえば、アカウントが 2015-02-16 のように以前の API バージョンに設定されている場合、特定のリクエストに対して versioning (バージョン管理) で API バージョンを変更しても、生成され送信先に送られる Event (イベント) オブジェクトは、引き続き 2015-02-16 API バージョンに基づきます。Event オブジェクトは、作成されると変更できません。たとえば、請求を更新しても、元の請求イベントは変更されません。そのため、アカウントの API バージョンを後で更新しても、既存の Event オブジェクトがさかのぼって変更されることはありません。新しい API バージョンを使用して /v1/events
を呼び出すことで以前の Event を取得しても、受信するイベントの構造には影響しません。テスト用のイベントの送信先を、デフォルトの API バージョンと最新の API バージョンのいずれかに設定できます。イベントの送信先に送られる Event は、イベントの送信先で指定されているバージョンに従って構造化されます。
Webhook 使用のベストプラクティス
これらのベストプラクティスを見直し、Webhook エンドポイントがセキュリティで保護され、システムで適切に機能することを確認してください。
重複するイベントを処理する
Webhook エンドポイントは、同じイベントを複数回受信する可能性があります。処理したイベント ID をログに記録し、すでにログに記録したイベントを処理しないようにすることで、重複するイベントの受信に対処することができます。
一部のケースでは、2 つの別々の Event オブジェクトが生成され、送信されます。これらの重複を識別するには、event.
とともに data.
のオブジェクトの ID を使用します。
構築済みのシステムに必要なイベントタイプのみをリッスンする
必要なイベントのタイプのみを受信するように、Webhook エンドポイントを設定します。その他のイベント (またはすべてのイベント) をリッスンすると、お客様のサーバーに過度の負荷がかかるため、お勧めしません。
ダッシュボードまたは API で、Webhook エンドポイントが受信するイベントを変更できます。
イベントを非同期で処理する
非同期キューで受信したイベントを処理するようにハンドラを設定します。非同期でイベントを処理することを選択した場合は、拡張性の問題が発生する可能性があります。Webhook の配信が急増すると (たとえば、すべてのサブスクリプションが更新される月初など)、エンドポイントホストが対処不可能になる場合があります。
非同期キューを使用することで、同時に発生するイベントをシステムが対応できる速度で処理できるようになります。
Webhook ルートを CSRF 保護から除外する
Rails、Django、その他のウェブフレームワークを使用している場合、貴社のサイトでは、すべての POST リクエストに 「CSRF トークン」が含まれていることを自動的に確認している可能性があります。これは、貴社とそのユーザーをクロスサイトリクエストフォージェリ の試行から保護するための重要なセキュリティ機能です。ただし、このセキュリティ対策は貴社サイトにおける正当なイベントの処理を妨げる可能性があります。この場合は、Webhook ルートを CSRF 保護から除外しなければならない可能性があります。
HTTPS サーバーでイベントを受信する
Webhook エンドポイント (本番環境で必要) に HTTPS URL を使用する場合、Stripe は Webhook データを送信する前に、お客様のサーバーへの接続が安全であることを確認します。これを機能させるには、お客様のサーバーが、有効なサーバー証明書で HTTPS をサポートするように正しく設定されている必要があります。Stripe の Webhook は、TLS バージョン v1.2 および v1.3 のみサポートしています。
エンドポイントの署名シークレットを定期的に取り消す
イベントが Stripe から送信されたことを確認するためのシークレットは、Workbench の Webhook タブで変更できます。シークレットを安全に保つために、定期的またはシークレットの侵害が疑われる場合にローテーション (変更) することをお勧めします。
シークレットを取り消すには、以下を行います。
- Workbench の Webhook タブで、シークレットをローテーションするエンドポイントをクリックします。
- オーバーフローメニュー () にアクセスし、シークレットの更新をクリックします。現在のシークレットキーをただちに有効期限切れにすることも、有効期限を最大 24 時間延長して、自社のサーバーの検証コードをご自身で更新する時間を確保することもできます。この間は、エンドポイントに対して複数のシークレットキーがアクティブになります。Stripe は、有効期限までシークレットキーごとに 1 つの署名を生成します。
イベントが Stripe から送信されたことを検証する
Stripe は、設定された IP アドレスリストから Webhook イベントを送信します。これらの IP アドレスから送信されたイベントのみを信頼してください。
この他、Webhook の署名を確認して、受信したイベントが Stripe から送信されたものであることを確かめてください。Stripe はエンドポイントに送信する Webhook イベントに署名するために、各イベントの Stripe-Signature
ヘッダーに署名を含めます。これにより、お客様は、イベントがサードパーティーではなく Stripe によって送信されたことを検証できます。署名を検証するには、Stripe の公式ライブラリを使用するか、自社のソリューションを使用して手動で検証します。
次のセクションでは、Webhook の署名を検証する方法を説明します。
- エンドポイントのシークレットを取得します。
- 署名を検証します。
エンドポイントのシークレットを取得する
Workbench の Webhook タブに移動し、すべてのエンドポイントを表示します。シークレットを取得するエンドポイントを選択し、クリックして表示をクリックします。
Stripe は、エンドポイントごとに一意のシークレットキーを生成します。テスト API キーと本番 API キーの両方に同じエンドポイントを使用する場合、シークレットはそれぞれ異なります。さらに、複数のエンドポイントを使用する場合は、署名を検証するエンドポイントごとにシークレットを取得する必要があります。この設定後、Stripe はエンドポイントに送信する各 Webhook への署名を開始します。
リプレイ攻撃を防止する
リプレイ攻撃とは、攻撃者が有効なペイロードとその署名を傍受し、それを再送信することを言います。そのような攻撃を低減するために、Stripe は Stripe-Signature
ヘッダーにタイムスタンプを含めています。このタイムスタンプは署名されたペイロードの一部であるため、署名によっても検証され、攻撃者は署名を無効にしなければタイムスタンプを変更できません。署名が有効でもタイムスタンプが古すぎる場合は、アプリケーションにペイロードを拒否させることができます。
Stripe のライブラリには、タイムスタンプと現在時刻の間に 5 分のデフォルトの許容範囲があります。この許容範囲は、署名を検証する際に追加のパラメーターを指定することで変更できます。ネットワークタイムプロトコル (NTP) を使用して、サーバーのクロックが正確であり、Stripe のサーバーの時間と同期していることを確認します。
よくある間違い
許容値 0
は使用しないでください。許容値 0
を使用すると、最新性チェックが完全に無効になります。
Stripe は、イベントをエンドポイントに送信するたびにタイムスタンプと署名を生成します。Stripe がイベントを再試行する場合 (たとえば、その前にエンドポイントが 2xx
以外のステータスコードで応答した場合)、新しい配信試行に対して新しい署名とタイムスタンプを生成します。
2xx レスポンスを素早く返す
エンドポイントは、タイムアウトの原因となる複雑なロジックを実行する前に、成功を示すステータスコード (2xx
) を速やかに返す必要があります。たとえば、会計システムで顧客の請求書を支払い済みとして更新する前に、200
のレスポンスを返さなければなりません。