Webhook を使用 しよう する理由 りゆう Stripe のシステムを構築 こうちく する際 さい 、自社 じしゃ のアプリが Stripe アカウントで発生 はっせい するイベントを受信 じゅしん できるようにすることをお勧 すす めします。こうすることで、バックエンドシステムは適宜 てきぎ アクションを実行 じっこう できます。
Webhook イベントを有効 ゆうこう にするには、Webhook エンドポイントを登録 とうろく する必要 ひつよう があります。登録 とうろく すると、Stripe アカウントで Event (イベント) が発生 はっせい した際 さい に、Stripe がリアルタイムのイベントデータをご利用 りよう のアプリの Webhook エンドポイントに追加 ついか します。Stripe は HTTPS を使用 しよう して、Event オブジェクト を含 ふく む JSON ペイロードとして Webhook イベントをアプリに送信 そうしん します。
Webhook イベントの受信 じゅしん は、顧客 こきゃく の銀行 ぎんこう が支払 しはら いを確定 かくてい したとき、顧客 こきゃく が支払 しはら いに対 たい して不審 ふしん 請求 せいきゅう を申請 しんせい したとき、継続 けいぞく 支払 しはら いが成功 せいこう したとき、サブスクリプションの支払 しはら いを回収 かいしゅう するときなど、非同期 ひどうき イベントをリッスンする際 さい に特 とく に便利 べんり です。
イベントの概要 がいよう Stripe はお客様 きゃくさま のアカウントでアクティビティーがあった際 さい にイベントデータを生成 せいせい し、送信 そうしん します。
イベントが発生 はっせい すると、Stripe は新 あら たに Event オブジェクト を作成 さくせい します。1 つの API リクエストで複数 ふくすう のイベントが作成 さくせい されることがあります。たとえば、顧客 こきゃく に新 あたら しいサブスクリプションを作成 さくせい すると、customer. subscription. created
イベントと payment_ intent. succeeded
イベントを受信 じゅしん することになります。
Webhook エンドポイントを Stripe アカウントに登録 とうろく すると、Stripe は、お客様 きゃくさま のアプリケーションがホストする登録 とうろく 済 ず みの Webhook エンドポイントに、POST リクエストの一部 いちぶ として Event オブジェクト を自動的 じどうてき に送信 そうしん できるようになります。Webhook エンドポイントが Event (イベント) を受信 じゅしん すると、アプリでバックエンドアクションを実行 じっこう できます (たとえば、payment_ intent. succeeded
イベントを受信 じゅしん した後 のち に、配送 はいそう 業者 ぎょうしゃ の API を呼 よ び出 だ して、配送 はいそう の予定 よてい を設定 せってい するなどします)。
Event オブジェクト Stripe が Webhook エンドポイントに送信 そうしん する Event オブジェクト では、変更 へんこう されたオブジェクトのスナップショットが提供 ていきょう されます。該当 がいとう する場合 ばあい 、変更 へんこう を示 しめ す previous_ attributes
プロパティが含 ふく まれることがあります。
Stripe がお客様 きゃくさま の Webhook に送信 そうしん するイベントタイプの一覧 いちらん をご覧 らん ください。
イベントペイロードの例 れい 以下 いか のイベントは、トライアル終了 しゅうりょう 時 じ のサブスクリプションの更新 こうしん を示 しめ しています。
イベントオブジェクトの構造 こうぞう イベントオブジェクトの構造 こうぞう を確認 かくにん すると、イベントと、そのイベントが提供 ていきょう する基 もと となる情報 じょうほう に対 たい する理解 りかい を深 ふか めることができます。
イベントタイプ 設定 せってい で Webhook エンドポイントがリッスンするすべてのイベントタイプ のイベントを受信 じゅしん します。受信 じゅしん したイベントの type
を使用 しよう して、アプリケーションで実行 じっこう が必要 ひつよう な処理 しょり を決定 けってい します。各 かく イベントの type
に対応 たいおう する data. object
は様々 さまざま です。
本番 ほんばん 環境 かんきょう とテスト環境 かんきょう エンドポイントに対 たい する、本番 ほんばん 環境 かんきょう とテスト環境 かんきょう の両方 りょうほう のイベント送信 そうしん リクエストを受信 じゅしん することがあります。これが該当 がいとう するのは、本番 ほんばん 環境 かんきょう とテスト環境 かんきょう の両方 りょうほう で 1 つのエンドポイントを使用 しよう している場合 ばあい や、Connect プラットフォームで本番 ほんばん 環境 かんきょう の Standard 連結 れんけつ アカウントに対 たい してテスト環境 かんきょう のリクエストを行 おこな っている場合 ばあい です。livemode
属性 ぞくせい を使用 しよう して、オブジェクトが本番 ほんばん 環境 かんきょう とテスト環境 かんきょう のどちらに存在 そんざい するかを確認 かくにん し、イベントの適切 てきせつ な処理 しょり を判断 はんだん します。
API バージョン api_ version
は、イベントの API バージョンを示 しめ し、含 ふく まれている data.object の構造 こうぞう を指定 してい します。エンドポイントは、設定 せってい されている API バージョンを使用 しよう してイベントを受信 じゅしん しますが、アカウントのデフォルトの API バージョンやイベントに関連 かんれん するリクエストの API バージョンと異 こと なる場合 ばあい があります。この属性 ぞくせい は、送信 そうしん 先 さき のエンドポイントによって決定 けってい され、異 こと なる API バージョンを使用 しよう して複数 ふくすう のエンドポイントに同 おな じイベントが送信 そうしん される可能 かのう 性 せい があることを示 しめ します。Stripe の Java、.NET、Go のクライアントライブラリを使用 しよう する場合 ばあい 、クライアント側 がわ で固定 こてい されている API バージョンを使用 しよう するようにエンドポイントの API バージョンを設定 せってい してください。そうしなければ、Event オブジェクトをデシリアライズ (逆 ぎゃく シリアル化 か ) できなくなるおそれがあります。
API から Event オブジェクトを取得 しゅとく する場合 ばあい 、data. object
構造 こうぞう の API バージョンを管理 かんり することはできません。代 か わりに、適切 てきせつ な API エンドポイントからそのオブジェクトを取得 しゅとく して、Stripe-Version
ヘッダーを使用 しよう し、API バージョンを指定 してい してください。
API リクエストイベント API リクエストの結果 けっか としてイベントが生成 せいせい されると、そのリクエストは request. id
として表示 ひょうじ されます。リクエストを行 おこな うときに idempotency_key を使用 しよう する場合 ばあい は、request. idempotency_ key
として含 ふく まれます。イベントの原因 げんいん を調査 ちょうさ する場合 ばあい は、この request
ハッシュを確認 かくにん します。
データオブジェクトと以前 いぜん の属性 ぞくせい *. updated
イベントの場合 ばあい 、イベントペイロードには、Stripe オブジェクトの変更 へんこう 内容 ないよう を調 しら べることができる data. previous_ attributes
が含 ふく まれています。上記 じょうき の例 れい の customer. subscription. updated
イベントの previous_ attributes
は、サブスクリプションの変更 へんこう 前 まえ の値 ね が status: trialing
であったことなどを示 しめ しています。data. object
は、active
のステータスを示 しめ しているため、サブスクリプションがトライアル期間 きかん から移行 いこう したことを示 しめ しています。
保留 ほりゅう 中 ちゅう の送信 そうしん このイベントに設定 せってい されているエンドポイントのうち、送信 そうしん に対 たい して正常 せいじょう に応答 おうとう していない数 かず を判断 はんだん するには、pending_ webhooks
を使用 しよう します。最初 さいしょ の送信 そうしん 時 じ には、エンドポイントが正常 せいじょう に応答 おうとう していないため、この値 ね が 1 以上 いじょう になります。このイベントを後 ご から取得 しゅとく する場合 ばあい 、各 かく エンドポイントが正常 せいじょう に応答 おうとう するため、pending_ webhooks
は最小 さいしょう 0 まで減 へ ります。送信 そうしん が失敗 しっぱい すると、請求 せいきゅう 書 しょ の確定 かくてい が遅 おく れる可能 かのう 性 せい があるため、invoice. created
イベントにとってこれは重要 じゅうよう です。
連結 れんけつ アカウントのイベント連結 れんけつ アカウントから Connect エンドポイント に送信 そうしん されるイベントには、account
が含 ふく まれます。account
を使用 しよう してオブジェクトが属 ぞく している連結 れんけつ アカウントを追跡 ついせき し、プラットフォームがイベントデータを適切 てきせつ に処理 しょり できるようにします。
Event オブジェクトが作成 さくせい される理由 りゆう この表 ひょう は、Event オブジェクト の生成 せいせい をトリガーする複数 ふくすう のシナリオを説明 せつめい したものです。
ソース トリガー ダッシュボード Stripe ダッシュボードで Stripe リソースを変更 へんこう することによって、API を呼 よ び出 だ す場合 ばあい 。 API アプリまたはウェブサイトでのユーザーアクションによって API コールが行 おこな われる場合 ばあい 。 API Stripe CLI を使用 しよう して手動 しゅどう でイベントをトリガーする場合 ばあい 。 API Stripe CLI で直接 ちょくせつ API を呼 よ び出 だ す場合 ばあい 。
始 はじ めるアプリで Webhook イベントの受信 じゅしん を開始 かいし するには、Webhook エンドポイントを作成 さくせい して登録 とうろく します。
Webhook エンドポイントハンドラを作成 さくせい して、イベントデータの POST リクエストを受信 じゅしん します。 Stripe CLI を使用 しよう して、ローカルで Webhook エンドポイントハンドラをテストします。 ダッシュボード または API を使用 しよう して、Stripe 内 ない にエンドポイントを登録 とうろく します。Webhook エンドポイントを保護 ほご します。 1 つのエンドポイントを登録 とうろく 、作成 さくせい して、複数 ふくすう のイベントタイプを同時 どうじ に処理 しょり するか、特定 とくてい のイベントに個別 こべつ のエンドポイントを設定 せってい することができます。
POST メソッドを使用 しよう して、Webhook リクエストの受 う け付 つ けが可能 かのう な HTTP または HTTPS エンドポイント関数 かんすう を設定 せってい します。ローカルマシンでエンドポイント関数 かんすう を開発 かいはつ 中 ちゅう の場合 ばあい 、HTTP を使用 しよう できます。公開 こうかい アクセスが可能 かのう になったら、Webhook エンドポイント関数 かんすう は HTTPS を使用 しよう する必要 ひつよう があります。
エンドポイント関数 かんすう を設定 せってい し、以下 いか を行 おこな うようにします。
Event オブジェクト で構成 こうせい される JSON ペイロードを使用 しよう して、POST リクエストを処理 しょり します。タイムアウトを引 ひ き起 お こす可能 かのう 性 せい のある複雑 ふくざつ なロジックの前 まえ に、成功 せいこう のステータスコード (2xx
) を素早 すばや く返 かえ します。たとえば、会計 かいけい システムで顧客 こきゃく の請求 せいきゅう 書 しょ を支払 しはら い済 ず みとして更新 こうしん する前 まえ に、200
のレスポンスを返 かえ す必要 ひつよう があります。 エンドポイントの例 れい このコードスニペットは、イベントタイプが受信 じゅしん されたことを確認 かくにん し、イベントを処理 しょり して、コード 200 のレスポンスを返 かえ すよう設定 せってい された Webhook 関数 かんすう です。
require 'json'
post '/webhook' do
payload = request . body . read
event = nil
begin
event = Stripe : : Event . construct_from (
JSON . parse ( payload , symbolize_names : true )
)
rescue JSON : : ParserError = > e
status 400
return
end
case event . type
when 'payment_intent.succeeded'
payment_intent = event . data . object
when 'payment_method.attached'
payment_method = event . data . object
else
puts "Unhandled event type: #{ event . type } "
end
status 200
end
Webhook エンドポイント関数 かんすう を本番 ほんばん 環境 かんきょう に移行 いこう する前 まえ に、アプリケーションの連携 れんけい をテストすることをお勧 すす めします。これを行 おこな うには、自身 じしん のローカルマシンにイベントを送信 そうしん するようローカスリスナーを設定 せってい し、テストイベントを送信 そうしん します。テストには、CLI を使用 しよう する必要 ひつよう があります。
ローカルエンドポイントにイベントを転送 てんそう する ローカルエンドポイントにイベントを転送 てんそう するには、CLI で以下 いか のコマンドを実行 じっこう し、ローカルリスナーを設定 せってい します。--forward-to
フラグは、テスト環境 かんきょう のすべての Stripe イベント をローカルの Webhook エンドポイントに送信 そうしん します。
stripe listen --forward-to localhost:4242/stripe_webhooks
注 ちゅう 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:5000
Webhook の署名 しょめい を確認 かくにん するには、リッスンコマンドの初期 しょき 出力 しゅつりょく から {{WEBHOOK_ SIGNING_ SECRET}}
を使用 しよう します。 Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
テストイベントをトリガーする テストイベントを送信 そうしん するには、Stripe ダッシュボードでオブジェクトを手動 しゅどう で作成 さくせい し、Webhook が登録 とうろく されているイベントタイプをトリガーします。あるいは、Stripe Shell または Stripe CLI で次 つぎ のコマンドを使用 しよう できます。
この例 れい では、payment_ intent. succeeded
イベントをトリガーします。
stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded ! Check dashboard for event details.
Stripe for VS Code を使用 しよう してイベントをトリガーする方法 ほうほう をご確認 かくにん ください。
Webhook エンドポイント関数 かんすう をテストしたら、Stripe がイベントの送信 そうしん 先 さき を把握 はあく できるように、開発 かいはつ 者 しゃ ダッシュボードまたは API の Webhook セクション を使用 しよう して、Webhook エンドポイントのアクセス可能 かのう な URL を登録 とうろく します。Stripe では最大 さいだい 16 の Webhook エンドポイントを登録 とうろく することができます。登録 とうろく された Webhook エンドポイントは、パブリックアクセスが可能 かのう な HTTPS URL である必要 ひつよう があります。
Webhook エンドポイントを登録 とうろく するための URL 形式 けいしき は、次 つぎ のとおりです。
https://<your-website>/<your-webhook-endpoint>
たとえば、ドメインが https://mycompanysite. com
で、Webhook エンドポイントへのルートが @app. route('/stripe_ webhooks', methods=['POST'])
の場合 ばあい 、エンドポイント URL には https://mycompanysite. com/stripe_ webhooks
を指定 してい します。
新 あたら しい Webhook エンドポイントを作成 さくせい するTo create a new webhook endpoint:
Open the Webhooks tab in Workbench. Click Create new endpoint . Select the API version for the events object you want to consume. If you’re using Connect , you can listen for Events on connected accounts . Otherwise, choose Events on your account . Select the event types that you want to send to a webhook endpoint, then click Continue . Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint. Click Create destination to create your webhook endpoint. Stripe API を使用 しよう して Webhook エンドポイントを登録 とうろく する プログラムで Webhook エンドポイントを作成 さくせい することもできます。
連結 れんけつ アカウントからイベントを受信 じゅしん するには、connect パラメーター を使用 しよう します。
次 つぎ の例 れい では、支払 しはら いが成功 せいこう または失敗 しっぱい したときに通知 つうち するエンドポイントを作成 さくせい します。
curl https://api.stripe.com/v1/webhook_endpoints \
-u sk_test_09l3shTSTKHYCzzZZsiLl2vA
: \
-d "url" = "https://example.com/my/webhook/endpoint " \
-d "enabled_events[]" = "payment_intent.payment_failed" \
-d "enabled_events[]" = "payment_intent.succeeded"
ハンドラですべての Webhook リクエストが Stripe によって生成 せいせい されたものであることを確認 かくにん して、実装 じっそう を保護 ほご する必要 ひつよう があります。公式 こうしき ライブラリを使用 しよう して Webhook の署名 しょめい を検証 けんしょう するか、手動 しゅどう で検証 けんしょう できます。
公式 こうしき ライブラリで検証 けんしょう する (推奨 すいしょう )
Stripe 公式 こうしき ライブラリで Webhook の署名 しょめい を検証 けんしょう する 署名 しょめい を検証 けんしょう するには、Stripe 公式 こうしき ライブラリを使用 しよう することをお勧 すす めします。イベントペイロード、Stripe-Signature
ヘッダー、エンドポイントのシークレットを指定 してい して検証 けんしょう を実行 じっこう します。検証 けんしょう に失敗 しっぱい するとエラーが返 かえ されます。
署名 しょめい 確認 かくにん エラーが発生 はっせい した場合 ばあい は、トラブルシューティング に関 かん するガイドをご覧 らん ください。
警告 けいこく Stripe で署名 しょめい の検証 けんしょう を実行 じっこう するには、未 み 加工 かこう のリクエスト本文 ほんぶん が必要 ひつよう です。フレームワークを使用 しよう している場合 ばあい は、元 もと の本文 ほんぶん に手 て が加 くわ えられないようにする必要 ひつよう があります。 未 み 加工 かこう のリクエスト本文 ほんぶん に何 なん らかの変更 へんこう が行 おこな われた場合 ばあい 、検証 けんしょう は失敗 しっぱい します。
Stripe . api_key = 'sk_test_09l3shTSTKHYCzzZZsiLl2vA'
require 'stripe'
require 'sinatra'
endpoint_secret = 'whsec_...'
set :port , 4242
post '/my/webhook/url' do
payload = request . body . read
sig_header = request . env [ 'HTTP_STRIPE_SIGNATURE' ]
event = nil
begin
event = Stripe : : Webhook . construct_event (
payload , sig_header , endpoint_secret
)
rescue JSON : : ParserError = > e
puts "Error parsing payload: #{ e . message } "
status 400
return
rescue Stripe : : SignatureVerificationError = > e
puts "Error verifying webhook signature: #{ e . message } "
status 400
return
end
case event . type
when 'payment_intent.succeeded'
payment_intent = event . data . object
puts 'PaymentIntent was successful!'
when 'payment_method.attached'
payment_method = event . data . object
puts 'PaymentMethod was attached to a Customer!'
else
puts "Unhandled event type: #{ event . type } "
end
status 200
end
Webhook との連携 れんけい のデバッグを行 おこな う Webhook エンドポイントにイベントを送信 そうしん する際 さい に、以下 いか のような複数 ふくすう のタイプの問題 もんだい が発生 はっせい することがあります。
Stripe が Webhook エンドポイントにイベントを送信 そうしん できない可能 かのう 性 せい がある Webhook エンドポイントで SSL の問題 もんだい が発生 はっせい している可能 かのう 性 せい がある ネットワーク接続 せつぞく が断続 だんぞく 的 てき である Webhook エンドポイントが、受信 じゅしん する予定 よてい のイベントを受信 じゅしん していない イベントの送信 そうしん を表示 ひょうじ する 特定 とくてい のエンドポイントのイベント送信 そうしん を表示 ひょうじ するには、Webhook タブで Webhook エンドポイントを選択 せんたく します。
アカウントでトリガーされたすべてのイベントを確認 かくにん するには、イベント タブを選択 せんたく します。
HTTP ステータスコードを修正 しゅうせい する イベントにステータスコード 200
が表示 ひょうじ されている場合 ばあい は、Webhook エンドポイントへの送信 そうしん が成功 せいこう したことを示 しめ しています。200
以外 いがい のステータスコードを受信 じゅしん する場合 ばあい もあります。次 つぎ の表 ひょう で、一般 いっぱん 的 てき な HTTP ステータスコードと推奨 すいしょう される解決 かいけつ 方法 ほうほう の一覧 いちらん をご覧 らん ください。
保留 ほりゅう 中 ちゅう の Webhook ステータス説明 せつめい 修正 しゅうせい (接続 せつぞく 不可 ふか ) ERR 宛先 あてさき サーバーへの接続 せつぞく を確立 かくりつ できません。ホストドメインがインターネットで一般 いっぱん に公開 こうかい されアクセス可能 かのう であることを確認 かくにん します。 (302
) ERR (またはその他 た の 3xx
ステータス) 宛先 あてさき サーバーがリクエストを別 べつ の場所 ばしょ にリダイレクトしようとしました。Webhook リクエストへのリダイレクト応答 おうとう は失敗 しっぱい と見 み なされます。Webhook エンドポイントの送信 そうしん 先 さき を、リダイレクトによって解決 かいけつ される URL に設定 せってい します。 (400
) ERR (またはその他 た の 4xx
ステータス) 宛先 あてさき サーバーがリクエストを処理 しょり できないか、処理 しょり しません。これは、サーバーがエラーを検出 けんしゅつ した場合 ばあい (400
)、宛先 あてさき URL にアクセス制限 せいげん が設定 せってい されている場合 ばあい (401
、403
)、または宛先 あてさき URL が存在 そんざい しない (404
) 場合 ばあい に発生 はっせい することがあります。エンドポイントがインターネットで一般 いっぱん に公開 こうかい されアクセス可能 かのう であることを確認 かくにん します。 エンドポイントが POST HTTP メソッドを受 う け入 い れることを確認 かくにん します。 (500
) ERR (またはその他 た の 5xx
ステータス) リクエストの処理 しょり 中 ちゅう に、宛先 あてさき サーバーでエラーが発生 はっせい しました。 アプリケーションのログを確認 かくにん して、500
エラーが返 かえ されている理由 りゆう を調 しら べます。 (TLS エラー) ERR 宛先 あてさき サーバーへの安全 あんぜん な接続 せつぞく を確立 かくりつ できませんでした。これらのエラーは通常 つうじょう 、宛先 あてさき サーバーの証明 しょうめい 書 しょ チェーン内 ない の SSL/TLS 証明 しょうめい 書 しょ または中間 ちゅうかん 証明 しょうめい 書 しょ の問題 もんだい によって発生 はっせい します。Stripe では、TLS バージョン v1.2 以降 いこう が必要 ひつよう です。SSL サーバーテスト を実行 じっこう して、このエラーの原因 げんいん となった可能 かのう 性 せい がある問題 もんだい を見 み つけます。(タイムアウト) ERR 宛先 あてさき サーバーで Webhook リクエストに応答 おうとう するのに時間 じかん がかかりすぎました。Webhook 処理 しょり コードで複雑 ふくざつ なロジックを延期 えんき して、成功 せいこう を示 しめ すレスポンスを即時 そくじ に返 かえ すようにしてください。
イベント送信 そうしん の動作 どうさ このセクションは、Stripe が Webhook エンドポイントにイベントを送信 そうしん する際 さい に想定 そうてい されるさまざまな動作 どうさ を理解 りかい するのに役立 やくだ ちます。
再 さい 試行 しこう の動作 どうさ 本番 ほんばん 環境 かんきょう では、Stripe は指数 しすう バックオフを使用 しよう して最長 さいちょう 3 日間 にちかん 、お客様 きゃくさま の Webhook エンドポイントに対 たい する特定 とくてい のイベントの配信 はいしん を試行 しこう します。ダッシュボードのイベント セクションで、次回 じかい の再 さい 試行 しこう が発生 はっせい する時期 じき を確認 かくにん できます。
テスト環境 かんきょう では、Stripe は数時間 すうじかん にわたって 3 回 かい 再 さい 試行 しこう します。これ以降 いこう は、ダッシュボードの Event セクションで、Webhook エンドポイントに対 たい して各 かく イベントの送信 そうしん を手動 しゅどう で再 さい 試行 しこう できます。見逃 みのが したイベントに対 たい してクエリを実行 じっこう して、任意 にんい の期間 きかん のデータを照合 しょうごう することもできます。
特定 とくてい のエンドポイントに対 たい して各 かく Webhook イベントの送信 そうしん を手動 しゅどう で再 さい 試行 しこう して、その再 さい 試行 しこう が成功 せいこう した場合 ばあい でも、自動 じどう での再 さい 試行 しこう は継続 けいぞく されます。
Stripe が再 さい 試行 しこう しようとしたときに、お客様 きゃくさま のエンドポイントが無効 むこう であるか削除 さくじょ されていた場合 ばあい 、それ以降 いこう 、そのイベントは再 さい 試行 しこう されません。ただし、お客様 きゃくさま が Webhook エンドポイントを無効 むこう にした後 のち 、Stripe から再 さい 試行 しこう を実行 じっこう するタイミングより前 まえ にその Webhook エンドポイントを再度 さいど 有効 ゆうこう 化 か した場合 ばあい は、以降 いこう の再 さい 試行 しこう は引 ひ き続 つづ き行 おこな われます。
動作 どうさ を無効 むこう にするテスト環境 かんきょう と本番 ほんばん 環境 かんきょう で、エンドポイントが 2xx
HTTP ステータスコードで応答 おうとう しない状況 じょうきょう が連続 れんぞく して何 なん 日 にち も続 つづ いた場合 ばあい 、Stripe は、設定 せってい が正 ただ しくないエンドポイントについて、メールで通知 つうち します。このメールには、エンドポイントが自動的 じどうてき に無効 むこう 化 か される時期 じき も示 しめ されます。
API のバージョン管理 かんり イベント発生 はっせい 時 じ のアカウント設定 せってい の API バージョンによって API バージョンが決 き まり、さらに Webhook で送信 そうしん される Event
オブジェクトの構造 こうぞう が決 き まります。たとえば、お客様 きゃくさま のアカウントで以前 いぜん の API バージョン (2015-02-16 など) が設定 せってい されている場合 ばあい 、バージョン管理 かんり を利用 りよう して特定 とくてい のリクエストの API バージョンを変更 へんこう しても、生成 せいせい され、お客様 きゃくさま のエンドポイントに送信 そうしん される Event
オブジェクトは API バージョン 2015-02-16 に基 もと づきます。
Event
オブジェクトは、作成 さくせい 後 ご に変更 へんこう することはできません。たとえば、支払 しはら いを更新 こうしん しても、元 もと の支払 しはら いイベントは変更 へんこう されません。このため、自身 じしん のアカウントの API バージョンを後 ご から更新 こうしん しても、既存 きそん の Event
オブジェクトが遡及 そきゅう 的 てき に変更 へんこう されることはありません。新 あたら しい API バージョンを使用 しよう して /v1/events
を呼 よ び出 だ して以前 いぜん のイベントを取得 しゅとく しても、受信 じゅしん したイベントの構造 こうぞう には影響 えいきょう しません。
テスト用 よう の Webhook エンドポイントは、デフォルトの API バージョンか、最新 さいしん の API バージョンのいずれかに設定 せってい できます。Webhook URL に送信 そうしん される Event
は、エンドポイントに指定 してい されているバージョンに従 したが って構造 こうぞう 化 か されます。また、プログラムによって、特定 とくてい の api_version のエンドポイントを作成 さくせい することもできます。
イベントの順序付 じゅんじょづ け Stripe は、イベントが生成 せいせい された順序 じゅんじょ で配信 はいしん されることを保証 ほしょう しません。たとえば、サブスクリプションを作成 さくせい することで、次 つぎ のイベントが生成 せいせい されるとします。
customer. subscription. created
invoice. created
invoice. paid
charge. created
(支払 しはら いが付随 ふずい する場合 ばあい )これらのイベントはこの順序 じゅんじょ どおりに配信 はいしん されるとは限 かぎ らないため、お客様 きゃくさま のエンドポイントは、状況 じょうきょう に応 おう じて配信 はいしん を処理 しょり する必要 ひつよう があります。API を使用 しよう して不足 ふそく しているオブジェクトを取得 しゅとく することもできます (たとえば、最初 さいしょ に受信 じゅしん したイベントが invoice. paid
であった場合 ばあい は、それに含 ふく まれる情報 じょうほう を使用 しよう して請求 せいきゅう 書 しょ 、支払 しはら い、サブスクリプションの各 かく オブジェクトを取得 しゅとく できます)。
Webhook 使用 しよう のベストプラクティス 以下 いか のベストプラクティスを参照 さんしょう して、Webhook のセキュリティを確保 かくほ し、構築 こうちく 済 ず みのシステムと適切 てきせつ に連携 れんけい するようにしてください。
重複 じゅうふく するイベントを処理 しょり するWebhook エンドポイントは、同 おな じイベントを複 ふく 数 すう 回 かい 受信 じゅしん する可能 かのう 性 せい があります。処理 しょり したイベント ID をログに記録 きろく し、すでにログに記録 きろく したイベントを処理 しょり しないようにすることで、重複 じゅうふく するイベントの受信 じゅしん に対処 たいしょ することができます。
構築 こうちく 済 ず みのシステムに必要 ひつよう なイベントタイプのみをリッスンする必要 ひつよう なイベントのタイプのみを受信 じゅしん するように、Webhook エンドポイントを設定 せってい します。その他 た のイベント (またはすべてのイベント) をリッスンすると、お客様 きゃくさま のサーバーに過度 かど の負荷 ふか がかかるため、お勧 すす めしません。
ダッシュボードまたは API で、Webhook エンドポイントが受信 じゅしん するイベントを変更 へんこう できます。
イベントを非同期 ひどうき で処理 しょり する 非同期 ひどうき キューで受信 じゅしん したイベントを処理 しょり するようにハンドラを設定 せってい します。非同期 ひどうき でイベントを処理 しょり することを選択 せんたく した場合 ばあい は、拡張 かくちょう 性 せい の問題 もんだい が発生 はっせい する可能 かのう 性 せい があります。Webhook の配信 はいしん が急増 きゅうぞう すると (たとえば、すべてのサブスクリプションが更新 こうしん される月 つき 初 はつ など)、エンドポイントホストが対処 たいしょ 不可能 ふかのう になる場合 ばあい があります。
非同期 ひどうき キューを使用 しよう することで、同時 どうじ に発生 はっせい するイベントをシステムが対応 たいおう できる速度 そくど で処理 しょり できるようになります。
Webhook ルートを CSRF 保護 ほご から除外 じょがい する Rails、Django、その他 た のウェブフレームワークを使用 しよう している場合 ばあい 、貴社 きしゃ のサイトでは、すべての POST リクエストに 「CSRF トークン」が含 ふく まれていることを自動的 じどうてき に確認 かくにん している可能 かのう 性 せい があります。これは、貴社 きしゃ とそのユーザーをクロスサイトリクエストフォージェリ の試行 しこう から保護 ほご するための重要 じゅうよう なセキュリティ機能 きのう です。ただし、このセキュリティ対策 たいさく は貴社 きしゃ サイトにおける正当 せいとう なイベントの処理 しょり を妨 さまた げる可能 かのう 性 せい があります。この場合 ばあい は、Webhook ルートを CSRF 保護 ほご から除外 じょがい しなければならない可能 かのう 性 せい があります。
class StripeController < ApplicationController
protect_from_forgery except : :webhook
def webhook
end
end
HTTPS サーバーでイベントを受信 じゅしん する Webhook エンドポイント (本番 ほんばん 環境 かんきょう で必要 ひつよう ) に HTTPS URL を使用 しよう する場合 ばあい 、Stripe は Webhook データを送信 そうしん する前 まえ に、お客様 きゃくさま のサーバーへの接続 せつぞく が安全 あんぜん であることを確認 かくにん します。これを機能 きのう させるには、お客様 きゃくさま のサーバーが、有効 ゆうこう なサーバー証明 しょうめい 書 しょ で HTTPS をサポートするように正 ただ しく設定 せってい されている必要 ひつよう があります。Stripe の Webhook は、TLS バージョン v1.2 および v1.3 のみサポートしています。
エンドポイントの署名 しょめい シークレットを定期 ていき 的 てき に取 と り消 け す イベントが Stripe から送信 そうしん されていることを確認 かくにん するために使用 しよう するシークレットは、ダッシュボードの Webhook セクション で変更 へんこう できます。エンドポイントごとに、シークレットを更新 こうしん をクリックします。現在 げんざい のシークレットキーをただちに有効 ゆうこう 期限切 きげんぎ れにすることも、有効 ゆうこう 期限 きげん を最大 さいだい 24 時 じ 間 あいだ 延長 えんちょう して、自社 じしゃ のサーバーの検証 けんしょう コードをご自身 じしん で更新 こうしん する時 とき 間 あいだ を確保 かくほ することもできます。この間 あいだ は、エンドポイントに対 たい して複数 ふくすう のシークレットキーが有効 ゆうこう です。Stripe は、有効 ゆうこう 期限 きげん までシークレットキーごとに 1 つの署名 しょめい を生成 せいせい します。
イベントが Stripe から送信 そうしん されたことを検証 けんしょう する Stripe は、設定 せってい された IP アドレスリストから Webhook イベントを送信 そうしん します。これらの IP アドレス から送信 そうしん されたイベントのみを信頼 しんらい してください。
この他 ほか 、Webhook の署名 しょめい を確認 かくにん して、受信 じゅしん したイベントが Stripe から送信 そうしん されたものであることを確 たし かめてください。Stripe はエンドポイントに送信 そうしん する Webhook イベントに署名 しょめい するために、各 かく イベントの Stripe-Signature
ヘッダーに署名 しょめい を含 ふく めます。これにより、お客様 きゃくさま は、イベントがサードパーティーではなく Stripe によって送信 そうしん されたことを検証 けんしょう できます。署名 しょめい を検証 けんしょう するには、Stripe の公式 こうしき ライブラリ を使用 しよう するか、自社 じしゃ のソリューションを使用 しよう して手動 しゅどう で検証 けんしょう します。
次 つぎ のセクションでは、Webhook の署名 しょめい を検証 けんしょう する方法 ほうほう を説明 せつめい します。
エンドポイントのシークレットを取得 しゅとく します。 署名 しょめい を検証 けんしょう します。エンドポイントのシークレットを取得 しゅとく する ダッシュボードの Webhook セクションを使用 しよう します。シークレットを取得 しゅとく するエンドポイントを選択 せんたく し、ページ右 みぎ 上 じょう でシークレットを探 さが します。
Stripe は、エンドポイントごとに一意 いちい のシークレットキーを生成 せいせい します。テスト API キーと本番 ほんばん API キー の両方 りょうほう に同 おな じエンドポイントを使用 しよう する場合 ばあい 、シークレットはそれぞれ異 こと なります。さらに、複数 ふくすう のエンドポイントを使用 しよう する場合 ばあい は、署名 しょめい を検証 けんしょう するエンドポイントごとにシークレットを取得 しゅとく する必要 ひつよう があります。その後 ご 、Stripe はエンドポイントに送信 そうしん する各 かく Webhook への署名 しょめい を開始 かいし します。
リプレイ攻撃 こうげき を防止 ぼうし する リプレイ攻撃 こうげき とは、攻撃 こうげき 者 しゃ が有効 ゆうこう なペイロードとその署名 しょめい を傍受 ぼうじゅ し、それを再 さい 送信 そうしん することを言 い います。そのような攻撃 こうげき を低減 ていげん するために、Stripe は Stripe-Signature
ヘッダーにタイムスタンプを含 ふく めています。このタイムスタンプは署名 しょめい されたペイロードの一部 いちぶ であるため、署名 しょめい によっても検証 けんしょう され、攻撃 こうげき 者 しゃ は署名 しょめい を無効 むこう にしなければタイムスタンプを変更 へんこう できません。署名 しょめい が有効 ゆうこう でもタイムスタンプが古 ふる すぎる場合 ばあい は、アプリケーションにペイロードを拒否 きょひ させることができます。
Stripe のライブラリには、タイムスタンプと現在 げんざい 時刻 じこく の間 あいだ に 5 分 ぶん のデフォルトの許容 きょよう 範囲 はんい があります。この許容 きょよう 範囲 はんい は、署名 しょめい を検証 けんしょう する際 さい に追加 ついか のパラメーターを指定 してい することで変更 へんこう できます。ネットワークタイムプロトコル (NTP ) を使用 しよう して、サーバーのクロックが正確 せいかく であり、Stripe のサーバーの時間 じかん と同期 どうき していることを確認 かくにん します。
Stripe は、イベントをエンドポイントに送信 そうしん するたびにタイムスタンプと署名 しょめい を生成 せいせい します。Stripe がイベントを再 さい 試行 しこう する場合 ばあい (たとえば、その前 まえ にエンドポイントが 2xx
以外 いがい のステータスコードで応答 おうとう した場合 ばあい )、新 あたら しい配信 はいしん 試行 しこう に対 たい して新 あたら しい署名 しょめい とタイムスタンプを生成 せいせい します。
エンドポイント は、タイムアウトの原因 げんいん となる複雑 ふくざつ なロジックを実行 じっこう する前 まえ に、成功 せいこう を示 しめ すステータスコード (2xx
) を速 すみ やかに返 かえ す必要 ひつよう があります。たとえば、会計 かいけい システムで顧客 こきゃく の請求 せいきゅう 書 しょ を支払 しはら い済 ず みとして更新 こうしん する前 まえ に、200
のレスポンスを返 かえ さなければなりません。
参照 さんしょう 情報 じょうほう