目次
問い合わせや決済の通知を受け取り、AIで分類して返信案を作る。Webhookは、外部サービスの出来事を自動化につなぐ便利な入口です。一方、インターネットから要求を受け付ける以上、その通知を誰が作り、何を何回実行してよいかを決める必要があります。
情報確認日：2026年10月15日。本記事はStripeとOWASPの公式資料をもとにした設計解説です。特定の決済事故を報告するものではありません。Stripeの挙動は同社の仕様として紹介し、すべてのWebhook提供元が同じ署名方式や再送方式を使うとは扱いません。
スポンサーリンク
通知のURLを知っていることは、送信者の証明ではない
Webhookは一般に、提供元が指定した受信URLへイベントを送る仕組みです。そのURLが長い、管理画面からしか見えないといった理由だけで、正当な要求と判定するべきではありません。URLがログや設定共有を通じて知られることもあります。
説明用に「支払い成功」の通知で会員権限を変更するシステムを考えます。受信したJSONに成功と書いてあるだけで有効化すると、送信者や対象を確認していない状態になります。AIが文章を読んで「正しい通知らしい」と評価しても、暗号学的な送信元確認の代わりにはなりません。
本サイトでは、受信、送信元の検証、イベントの記録、業務上の照合、AI処理、外部への実行を分ける構成を提案します。モデルへ通知を渡す前に、プログラムで確認できる条件を確定することが重要です。 根拠資料：OWASP：Webhook Security Cheat Sheet。
署名を検証するときは、受信した本文を変えない
Stripeは、受信した本文のraw body、Stripe-Signatureヘッダー、受信先の署名用シークレットを使う検証を説明しています。JSONを一度読み込んで整形し直すと、意味が同じに見えても、署名の対象となるバイト列が変わる場合があります。 根拠資料：Stripe Docs：Webhooks。
フレームワークや中継処理が、署名検証より前に本文を変換しないかを確認します。改行、文字コード、空白などを手動で調整して通そうとするのではなく、公式SDKが必要とする入力をそのまま確保する方法を使います。
署名用の秘密と、通常のAPI呼び出し用のキーは役割が異なります。テスト環境、実環境、CLIからの転送などでも値が違う場合があるため、どの受信口に対する資格情報かを確認してください。検証エラーを直すために、署名確認を無効にして運用しないことが基本です。 根拠資料：Stripe Docs：Manage webhook endpoints。
スポンサーリンク
署名が正しくても、古い要求の再利用を考える
正しい本文と署名を複製された場合、同じ内容が再び送られる可能性があります。提供元が署名へ時刻を含める方式なら、時刻も検証し、古すぎる通知を拒否する仕組みが再送攻撃の対策になります。サーバーの時計のずれにも注意します。
Stripeの資料では、署名に含むタイムスタンプの検証と、再配信ごとに新しい署名・時刻を作る挙動が説明されています。したがって、配送の時刻と業務上のイベントが起きた時刻を混同しないことが必要です。
ただし、許容時間内に同じ通知が届くことや、提供元が正当な再配信を行うことは別に残ります。時刻の検証を重複排除の代わりにはできません。署名、鮮度、イベントの重複、業務の状態を、それぞれ違う検査として扱います。
同じイベントは、二回届く前提で設計する
Stripeは同じイベントが複数回届く場合があることを説明しています。イベントIDを記録し、処理済みのものを再実行しない方法が基本です。単に同じ本文かを比較するだけでは、意味のある識別と一致しない場合があります。
本サイトでは、イベントIDと提供元・受信先の組み合わせを一意に記録し、受付状態と業務処理状態を分ける設計を提案します。受信済み、処理中、完了、要再試行を区別すると、途中の障害から復旧しやすくなります。
同時に届いた要求が、双方とも未処理と判断しないことも必要です。データベースの制約などで受付を一つに確定し、同じイベントへ同じ結果を返す仕組みを検証します。画面の二重クリック防止や、単一プロセス内の変数だけでは足りない場合があります。
スポンサーリンク
業務上の重複は、イベントIDだけでは判定できないことがある
別のイベントIDでも、同じ対象について似た通知が来る場合があります。Stripeの資料も、対象オブジェクトのIDとイベント種別を使う重複の識別を説明しています。ただし、すべての更新を同一とみなすと、正当な状態変化まで捨てる可能性があります。
例えば、一つの注文への複数の支払い、返金、訂正は、単に注文IDが同じというだけで無視できません。業務の状態遷移と、イベントが意味する操作を決める必要があります。「重複だから捨てる」という規則も、仕様としてレビューの対象にします。
AIの処理も、外部へ送る前と後で分けます。返信案を二回生成することと、顧客へ同じ返信を二回送ることでは影響が違います。費用の制限と、外部への操作の一度限りの実行を、それぞれ設計することを提案します。
届く順序が、そのまま業務の順序とは限らない
通知が遅延したり、再配信されたりすると、新しい状態の通知が古い状態より先に届くことがあります。Stripeも配送順序への依存を避けるよう説明しています。受信順だけで状態を上書きすると、完了した処理を未完了へ戻すなどの不整合が起こり得ます。
本サイトでは、提供元のAPIから現在の対象状態を取得する必要がある場面と、イベントの履歴を保存すべき場面を分ける方法を提案します。どちらが正しいかは業務によるため、すべてを最後に届いた通知で更新する実装にしません。
時刻にも注意します。イベントの作成時刻が同じ粒度で重なることがあり、時刻だけを一意キーや正確な処理順の根拠にするべきではありません。提供元のIDや版、状態と、自社の更新条件を照合します。
早い応答と、処理を失わない保存を両立する
AIの生成が終わるまでWebhookのHTTP接続を保持すると、提供元のタイムアウトや再送につながる場合があります。Stripeの資料は早い成功応答と非同期処理を説明しています。ただし、何も保存せず先に成功を返すと、応答後の障害で仕事を失いかねません。
本サイトでは、検証済みのイベントを永続的に受け付けた後、AIを使う重い処理をキューへ渡す構成を提案します。応答の成功と、業務処理の成功を分け、後から未完了の仕事を確認できるようにします。キューへ保存できなかった場合の返答も決めます。
処理中に落ちた場合は、再試行の対象と回数を制御します。外部送信が成功したか不明なら、結果を照会できる設計が望まれます。同じ依頼を無条件に繰り返すのではなく、提供元の結果IDや自社の実行記録を使って判断します。
受信口の設定変更も、処理中のイベントへ影響する
署名用の秘密を切り替えたり、受け取るイベントを減らしたりするとき、すでに配送待ちの通知や再試行中の仕事が残ることがあります。本サイトでは、変更前後の受信先、環境、イベントの版を記録し、どの条件で受け付けたかを後から照合できるようにすることを提案します。
秘密の切り替え方式は提供元ごとに異なります。正常な更新では重複有効期間を使える場合がありますが、漏えい時に古い秘密を残す期間には危険も残ります。配送エラーを避けるためだけに古い値を無期限に残さず、失効と再配信の手順を確認してください。設定変更後の最初の成功通知だけでなく、古い値の扱いも点検します。
スポンサーリンク
AIを止めても、イベントを失わない構成にする
モデル提供元の障害や生成枠の不足があるとき、Webhookの受付まで失敗させると、外部サービスの再試行が重なって混雑する場合があります。受付と生成を分けていれば、検証済みイベントを保留し、復旧後に業務上必要なものだけ処理できます。保留には件数と保存期間の上限を設けます。
ただし、時間がたつと、最初の通知に基づく返信や権限変更が不要になっていることもあります。再開時には現在の業務状態と対象を確認し、古い通知から今は無効な操作を起こさないことを提案します。順序、重複、時間経過を別々に考えると、AIの復旧を待っている間にも安全なサービス運用を保ちやすくなります。
署名確認の後にも、対象と操作を照合する
WordPressの独自受信口を作る場合も、通常の会員向け画面とは認証の前提が異なることを確認します。提供元が使えないブラウザー用のnonceを要求して失敗させたり、その逆に通知用の例外を一般の管理操作まで広げたりしないよう、受信経路を限定します。
正当な提供元が送った通知でも、自社の想定と違うアカウント、環境、イベント種別の可能性があります。必要な通知だけを受け取り、関連する注文や会員が自社の対象かを確認します。正しい署名を、あらゆる業務変更への包括的な許可にしません。
通知の本文に利用者由来の文章が含まれる場合、AIには外部データとして渡します。その文章から、新しい送信先や権限変更を勝手に決めないようにします。正当な送信サービスと、その中に入る文章の信頼は別です。
- 改変された本文や別の秘密では、署名検証が失敗する。
- 古い配送と正当な再配信を、提供元の仕様に沿って扱える。
- 同じ通知の同時受信でも、外部への処理が重複しない。
- 順序の入れ替えや途中の停止後も、状態が一貫する。
- 未知のイベントや別環境の通知で、会員権限を変更しない。
検証環境で、同じイベント、逆順、タイムアウト、キュー障害を試してください。署名検証は重要な入口ですが、その後の一度限りの実行と業務上の認可も必要です。AIへ仕事を渡す前に、通知から実行までの状態を説明できるようにしましょう。
スポンサーリンク
