Webhook

イベントから署名付き要求を送り、検証後すぐ受領して待ち行列へ渡す失敗時の待ち時間を増やす再試行再試行と、イベントIDによる重複排除までを一つの配信として見る

送信から処理まで

Pollingとの違い

polling（ポーリング／定期問い合わせ）は、利用側が一定間隔でAPIへ「変化したか」を問い合わせる方式です。単純ですが、変化がなくても要求が発生し、設定した間隔より早くは検知できません。

Webhookはイベント時だけプッシュでき低遅延ですが、利用側側にインターネットから到達可能なHTTPSエンドポイント、認証、再送、監視が必要です。Webhookで通知だけ受け、最新状態はAPIで取り直す組み合わせもあります。

ペイロードはイベントの事実として読む

ペイロードにはイベント種類、イベント発生時刻、配信試行時刻、イベントID、データを含めます。イベント発生と配信は別時刻で、再送ごとに配信時刻だけ変わる設計があります。

完全ペイロードは必要データを同梱し追加API呼び出しを減らします。thinペイロードはIDと変化の要点だけ送り、利用側が権限付きAPIで最新状態を取得します。機密性、大きさ、整合性で選びます。

署名検証

1. 生の要求本文を保持するJSONを解析・整形してから計算すると、送信時バイト列と一致しない場合があります。
2. タイムスタンプを許容範囲で確認する古い正規要求の再送を防ぎます。
3. 事業者指定のメッセージを計算するイベントID、タイムスタンプ、本文等を正しい順で結合します。
4. 安全なライブラリーで署名を比較するHMACなら処理時間が入力値に左右されない比較関数を使い、アルゴリズムを勝手に変更しません。
5. 検証後に解析・処理する失敗要求を業務ロジックへ渡しません。

HTTPSと署名は役割が違う

HTTPSは通信経路の暗号化と接続先サーバーの認証を行います。ペイロード署名は受信したメッセージが共有秘密情報等を持つ送信者から来て、改ざんされていないかを検証します。

署名だけではペイロードの内容を暗号化しません。機密データを含むならHTTPSを必須にし、ログへ本文と秘密情報を残し過ぎません。

受信後すぐ待ち行列へ置く

事業者のタイムアウトより長いデータベース処理や外部API呼び出しを同期で行うと、処理中に再送されやすくなります。署名検証、大きさ制限、重複鍵記録、永続的な待ち行列投入までを短く行い、成功応答を返します。

ワーカーは待ち行列から取り、失敗を再試行またはデッドレター待ち行列へ移します。受領成功と業務処理成功を別指標で監視します。

再送と待ち時間を増やす再試行

タイムアウト、接続障害、失敗状態で事業者が再送する場合があります。一定間隔ではなく時間を広げる待ち時間を増やす再試行を使う実装が多く、最大回数や保存期間を超えると停止します。

利用側障害中にイベントが失われる可能性へ、配信ログ、手動再配送、イベント一覧API、差分調整ジョブを用意します。

重複と冪等性

同じイベントIDを複数回受ける前提で、処理済みIDを一意制約付きで記録します。「確認してから追加」だけでは同時処理競合が起きるため、データベーストランザクションや原子的な操作を使います。

課金、クーポン発行、メール送信のような副作用はイベントIDを下流の冪等性鍵にも渡します。

順序と古いイベント

並列送信と再送により、作成・更新・削除が発生順で届くとは限りません。リソースバージョン、順序、更新日時を比較し、古いイベントで新状態を上書きしないようにします。

順序保証が必要なら、事業者の区画規則や順序仕様を確認し、同じリソースを直列に処理します。

エンドポイント登録の安全性

任意URLを登録できる機能はSSRFの入口になり得ます。スキームをHTTPSへ限定し、プライベート・link-ローカルアドレス、リダイレクト先、DNS 再割り当てを検査します。登録時チャレンジで所有を確認する方式もあります。

秘密情報はエンドポイントごとに分け、回転期間は新旧鍵を安全に検証します。送信元IP 許可リストだけに依存せず署名を確認します。

WebhookはイベントをHTTP要求としてプッシュする配信機構です。署名付き生の本文を検証し、短時間で受領して待ち行列へ渡し、再送・重複・順序ずれ・未達を前提に処理します。

WebhookをHTTP callbackとして扱うmodel、payload、signature・timestamp・event ID、retry等の共通指針：Standard Webhooks Specification