Stripe Webhookとは、Stripe で決済などの出来事が起きた時に、登録した HTTPS の受け口へ出来事の中身を JSON で送る仕組みです。
- 受け口の登録から、
Stripe-Signatureの署名を生の本文で確かめて成功の返事を返すまでの手順 - テストモードで
stripe listen・stripe trigger・テスト用のカードを使って撃つ方法と、無効になっていた受け口を戻した記録 - 店ごとの受け口と署名の鍵、テストか本番かの取り違え、使っていない受け口の片づけで、当社が実際に見た返事
当社は AIエージェント の席に、サイト作りの道具の決済の受け口を作らせ、出した後の確かめまで撃たせています。この頁は Stripe の公式の文書の手順に、その時の記録を並べた物です。Webhook という仕組みそのもの(API との違い・HMAC 署名の考え方)は Webhook の頁 にまとめてあり、ここでは Stripe に固有の所だけを書きます。受け口を置く先は Cloud Run、署名の鍵の保管は Secret Manager の頁にあります。
Stripe Webhook の受け方:登録から 2xx を返すまでの 5 手
Stripe の文書が示す流れを、受け口を作る側の手順に並べ直すと次のとおりです。
| 手 | やる事 | 文書にある決まり |
|---|---|---|
1 | ワークベンチの Webhook タブ(または Event Destinations API)で、受け口の URL と受けるイベントの種類を登録する | 公開された HTTPS の URL が要る。登録できる送信先は 1 アカウントに最大 16 個 |
2 | 登録した受け口の署名シークレットを控える | whsec_ で始まる。受け口ごとに別の値で、同じ受け口をテストと本番の両方に使ってもシークレットはそれぞれ違う |
3 | POST を受ける口を作り、生の本文・ Stripe-Signature の見出し・シークレットの 3 つで署名を確かめる | 本文に手が加わると検証は失敗する |
4 | 確かめが通ったら、重い処理の前に 2xx を返す | 複雑なロジックの前に素早く 2xx を返す。処理は非同期のキューで回すよう勧めている |
5 | 処理済みのイベント ID を記録し、同じ ID は処理しない | 同じイベントが複数回届く事がある |
出典: Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「イベントの仕組み」(いずれも 2026-11-10 に確認)。
Rails や Django のように POST に CSRF のトークンを求めるフレームワークでは、Webhook の道だけを CSRF の保護から外す必要がある事も、同じ文書に書かれています。
Stripe-Signature の確かめ方:t と v1 を、生の本文で照らす
Stripe はすべての Webhook に Stripe-Signature の見出しを付けて送ります。中身は t=タイムスタンプ,v1=署名 の形の 1 行で、テストのイベントには偽の v0 の署名も足されます。文書は公式のライブラリ(スナップショットのイベントなら constructEvent())で確かめる事を勧め、手で書く場合の手順も載せています(Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・2026-11-10 に確認)。
| 手 | 手で確かめる時にやる事 | 外しやすい所 |
|---|---|---|
1 | 見出しを , で分け、t の値と v1 の値を取り出す | v1 以外のスキームは無視する(ダウングレード攻撃を防ぐため) |
2 | タイムスタンプ・ .・生の本文をつないで signed_payload を作る | JSON に読み直した本文や、空白・キーの順が変わった本文では一致しない |
3 | 署名シークレットを鍵にして signed_payload の HMAC-SHA256 を計算する | CLI の stripe listen が出すシークレットと、ダッシュボードの受け口のシークレットは別物 |
4 | 計算した値と見出しの署名を、時間が一定の比較で照らす | 普通の等号はタイミング攻撃に弱い |
5 | 一致したら、今の時刻とタイムスタンプの差が許容の内かを見る | 公式のライブラリの既定は 5 分。許容を 0 にすると新しさの確かめが丸ごと無くなる |
出典: Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「Webhook エンドポイントを管理する」(いずれも 2026-11-10 に確認)。
いちばん多い失敗は、フレームワークが先に本文を読んでしまう事です。文書は、Express なら Webhook の道を app.use(express.json()) より前に置く事、Next.js の Pages Router なら bodyParser を切る事を例に挙げています。Stripe は再送のたびに新しいタイムスタンプと署名を作り直すので、再送の知らせが許容の 5 分で落ちる事はありません(Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「Webhook エンドポイントを管理する」・2026-11-10 に確認)。署名に加えて、Stripe の送り元の IP だけを通す許可リストも併せて使うよう勧められています。
当社の作り:店ごとの住所と、店ごとの署名の鍵
当社のサイト作りの道具は、自分の頁から自分の商品や相談を売る人のための道具です。決済は、各社が自分の Stripe の鍵を入れてつなぐ機能で、Stripe からの知らせは各社の合言葉(署名の鍵)だけで確かめます。当社だけが通れる特別な道(全社に効く共通の合言葉)は残していません(社の実測 2026-10-07)。
受け口の住所も店ごとに分け、/api/webhooks/stripe/<店の id> の形にしました。住所の店の鍵でしか署名が通らないので、ある店の鍵で作った知らせを別の店の住所へ送っても受け付けません。出した直後に、偽の知らせを 2 通り撃って確かめました(社の実測 2026-10-07)。
| 撃った知らせ | 返った | 確かめた事 |
|---|---|---|
存在しない店の住所への知らせ | 401 | 知らない店の口が開いていない |
署名の無い知らせ | 401 | 署名を確かめる前に処理へ進まない |
出典: 社の実測 2026-10-07。
鍵と住所を店ごとにしておくと、ある店が鍵を差し替えたり Stripe をやめたりしても、ほかの店の受け口に影響しません。共通の合言葉がひとつ残っていると、それが漏れた時に全店の受け口が開くので、当社はその道を作らない方を選びました。
テストモードで撃つ:stripe listen・stripe trigger とテスト用のカード
Stripe の文書は、本番で有効にする前に、サンドボックスでイベントを起こすか、Stripe CLI でテストのイベントを送って確かめるよう勧めています。撃ち方は次のとおりです。
| 撃ち方 | やり方 | 向いている時 |
|---|---|---|
手元の受け口へ転送 | stripe login の後、stripe listen --forward-to localhost:4242/webhook。出てきた whsec_ の値を手元の受け口の鍵にする | 公開の URL がまだ無い。手元で署名の確かめを作っている |
イベントだけを起こす | stripe trigger payment_intent.succeeded のように、イベントの種類を指定して起こす | 特定のイベントの処理だけを見たい |
本当に買ってみる | サンドボックス(テストモード)の決済画面で、テスト用のカード 4242 4242 4242 4242・将来の有効期限・任意の 3 桁で払う | 決済画面から注文の完了まで、出した受け口を通しで見たい |
出典: Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「テスト」(いずれも 2026-11-10 に確認)。テスト用のカードの取引では資金は動かないと書かれています。
当社は 3 つ目の「本当に買ってみる」で確かめました。テストモードでテスト用のカード(4242…)で買うと、店ごとの受け口が 200 を返し、注文が「完了」になりました。ブランドごとに店を分けた後も撃ち直し、Stripe をつないだ店と、別の決済会社をつないだ店が、それぞれの受け口で 200 になりました(社の実測 2026-10-21)。
stripe trigger は早くて便利ですが、確かめられるのは「そのイベントの処理」までです。決済画面の作り、どの店の住所へ届くか、注文の状態が変わるかまで見るには、テスト用のカードで最後まで買う方が確かでした。
無効(disabled)になった受け口は、ダッシュボードで戻してから撃つ
上のテストの日、撃つ前にダッシュボードを見ると、Stripe のテスト用の受け口(Webhook のエンドポイント)が「無効(disabled)」になっていました。このまま買っても知らせは届かないので、ダッシュボードで有効に戻してから撃ちました(社の実測 2026-10-21)。
無効の受け口について、Stripe の文書が書いている事は次のとおりです。
| 場面 | Stripe の動き |
|---|---|
送信先を無効にしている間 | その送信先へのイベントの送信をすべて止める |
有効に戻した後 | イベントの送信を再開する |
再送の時に送信先が無効か削除されていた | そのイベントのそれ以後の再送はしない |
再送の前に無効にして、再送の時までに有効に戻した | それ以後の再送は続く |
出典: Stripe Docs「イベントの仕組み」(2026-11-10 に確認)。
つまり、無効の間に起きたイベントは、戻しただけでは届き直さない事があります。取りこぼしは、List Events API に delivery_success=false を付けて、配信に失敗したイベントを引き直して処理します。この API が返すのは過去 30 日に作られたイベントだけです(Stripe Docs「Webhook エンドポイントを管理する」・2026-11-10 に確認)。テストの前に、受け口が有効かをダッシュボードで見る手を、撃つ手順の頭に入れておくと、「撃ったのに何も起きない」で迷う時間が減ります。
テストか本番か:受け口の門で分け、台帳まで渡す
Stripe のイベントには livemode という欄があり、テストのイベントでは false になります(Stripe Docs「イベントの仕組み」・2026-11-10 に確認)。当社はこの区別を 2 か所で使っています。
1 つは受け口の門です。本番では、試験用と印を付けた会社でない会社のテストモードの決済は、注文にしない作りにしています。上のテストの日、試験用でない会社のテスト決済が 2 件あり、どちらも注文になりませんでした。設計どおりの動きです(社の実測 2026-10-21)。本物の店の売上の表に、テストの買い物が混ざらないための門です。
もう 1 つは台帳です。知らせを受けて台帳に書く口が、テストか本番か(mode)を渡しておらず、台帳の 1 行の mode が空になっていました(社の実測 2026-10-09)。
| 直した所 | やった事 |
|---|---|
空だった台帳の行 | mode を test に直した |
台帳に書く口 | mode を受け取って書くように直した |
戻りを防ぐ試験 | 直しを外すと赤になる試験を足した |
出典: 社の実測 2026-10-09。
受け口の門でテストを見分けていても、その先の口が mode を落とすと、台帳では本番とテストの区別がつかなくなります。mode は受け口で読んだ所から、台帳に書く所まで、途中の口すべてで渡す物として扱っています。
使っていない受け口を消す:400 から 404 へ
ブルーランプ本体に、使っていない Stripe の受け口が残っていました。30 日の呼び出しが 0 で、Stripe 側にもこの受け口へ向く Webhook の登録とイベントが 0 だった事を確かめてから消しました(社の実測 2026-10-28)。
| 撃った知らせ | 消す前 | 消した後 |
|---|---|---|
署名なしの知らせ | 400 | 404 |
偽の署名の知らせ | 400 | 404 |
出典: 社の実測 2026-10-28。
消す前の 400 は「口は在るが、署名が通らない」という返事で、消した後の 404 は「口そのものが無い」という返事です。返事が 400 から 404 に変わった事で、口が本当に無くなったと確かめられます。使わない受け口は、署名の確かめを持っていても、外に開いた口が 1 つ多い状態です。呼び出しと Stripe 側の登録の両方が 0 である事を見てから消すと、本物の知らせを落とす心配がありません(社の実測 2026-10-28)。決済・Webhook に触れる変更を入れる前の確かめ方は、Webhook の頁に書いています。
再送・重複・順番:Stripe の配信の決まり
受け口が成功の返事以外を返したり時間切れになったりした時の Stripe の動きは、次のとおりです。
| 項目 | Stripe の文書の決まり |
|---|---|
自動の再送(本番) | 指数バックオフで最長 3 日間 |
自動の再送(サンドボックス) | 数時間のうちに 3 回 |
手での再送(ダッシュボード) | イベントの作成から最大 15 日間 |
手での再送(CLI の stripe events resend) | イベントの作成から最大 30 日間 |
失敗の扱いになる返事 | 3xx のリダイレクト、4xx、5xx、TLS のエラー、時間切れ |
重複 | 同じイベントが複数回届く事がある。処理済みのイベント ID を記録して見分ける |
順番 | 生成された順に届く保証は無い。 created で順や処理済みを判断しない |
署名シークレットの差し替え | 古いシークレットを最長 24 時間残せる。その間は鍵ごとに署名が付く |
出典: Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「Webhook エンドポイントを管理する」(いずれも 2026-11-10 に確認)。
手でイベントを処理し直しても、Stripe はそのイベントを未配信と見て自動の再送を続けます。処理済みの ID が来たら、処理を飛ばして 200 を返せば再送が止まる、と文書は書いています(Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」・Stripe Docs「Webhook エンドポイントを管理する」・2026-11-10 に確認)。
よくある質問
Stripe Webhook の署名の確かめが失敗します。何を見ればよいですか?
Stripe の文書は、いちばん多い原因を「間違ったシークレット」としています。stripe listen が出すシークレットとダッシュボードの受け口のシークレットは別物なので、使っている値を出して照らします。次に、フレームワークが本文を JSON に読み直していないか、Stripe-Signature が t=…,v1=… の形で取れているかを見ます(Stripe Docs・2026-11-10 に確認)。
Stripe Webhook をローカルでテストするには?
Stripe CLI で stripe listen --forward-to localhost:4242/webhook を走らせ、表示された whsec_ の値を手元の受け口の鍵にして、stripe trigger payment_intent.succeeded などでイベントを起こします(Stripe Docs・2026-11-10 に確認)。出した受け口を通しで見るなら、テストモードでテスト用のカードで最後まで買うと、当社では受け口の 200 と注文の「完了」まで確かめられました(社の実測 2026-10-21)。
Stripe の Webhook エンドポイントが無効(disabled)になっていたら?
ダッシュボードの Webhook タブで有効に戻すと、Stripe はイベントの送信を再開します。ただし再送の時に無効だったイベントは、それ以後再送されないので、List Events API に delivery_success=false を付けて取りこぼしを引き直します(Stripe Docs・2026-11-10 に確認)。当社はテストの前に無効になっていた受け口を戻してから撃ちました(社の実測 2026-10-21)。
Stripe Webhook のテストのイベントと本番のイベントはどう見分けますか?
イベントの livemode の欄で見分けます。テストでは false です(Stripe Docs・2026-11-10 に確認)。当社は、受け口の門で分けるだけでなく、台帳に書く口まで mode を渡すように直し、直しを外すと赤になる試験を足しました(社の実測 2026-10-09)。
Stripe Webhook の再送はいつまで続きますか?
本番では指数バックオフで最長 3 日間、サンドボックスでは数時間のうちに 3 回です。ダッシュボードからの手での再送は作成から 15 日、CLI からは 30 日まで使えます(Stripe Docs・2026-11-10 に確認)。
出典
- Stripe Docs「Webhook エンドポイントで Stripe イベントを受信する」 https://docs.stripe.com/webhooks(2026-11-10 に確認)
- Stripe Docs「Webhook エンドポイントを管理する」 https://docs.stripe.com/events/manage-webhook-endpoints(2026-11-10 に確認)
- Stripe Docs「イベントの仕組み」 https://docs.stripe.com/events/how-events-work(2026-11-10 に確認)
- Stripe Docs「テスト」 https://docs.stripe.com/testing(2026-11-10 に確認)
- 社の実測 2026-10-07(店ごとの鍵・共通の合言葉を残さない・存在しない店と署名なしへの 401)・2026-10-09(台帳の mode の空と直し)・2026-10-21(テスト用のカードでの 200 と注文の完了・無効の受け口を戻した・試験用でない会社のテスト決済を注文にしない)・2026-10-28(使っていない受け口を消し、400 から 404 へ)
ブルーランプ 編集部/更新日 2026-11-10