Webhookの信頼性チェックリスト：リトライ、冪等性、再実行

実務でWebhookが信頼できなく感じる理由

Webhookはシンプルです：何かが起きたときに一方のシステムがもう一方へHTTPリクエストを送るだけです。 「注文が発送された」「チケットが更新された」「デバイスがオフラインになった」。アプリ同士のプッシュ通知のようなものです。

デモではハッピーパスが速くてきれいなので信頼できて見えます。実務では、Webhookはあなたの管理外にあるシステムの間に入ります：CRM、配送業者、ヘルプデスク、マーケティングツール、IoTプラットフォーム、別チームが運用する内部アプリなど。決済以外では、配信保証や安定したイベントスキーマ、一貫したリトライ動作を期待しにくくなります。

最初に出る症状はたいてい混乱を招きます：

• イベントの重複（同じ更新が二度届く）
• イベントの欠落（変更があったのに通知が届かない）
• 遅延（更新が数分や数時間後に届く）
• 順序のずれ（「閉じた」が「開いた」より先に届く）

不安定なサードパーティは失敗の声が小さいため、ランダムに見えます。プロバイダがタイムアウトしたが実際にはリクエストを処理していたり、ロードバランサが接続を切った後に送信側が再試行したり、短時間のダウンの後に古いイベントを一斉に送ってくることもあります。

例えば配送パートナーが「配達済み」のWebhookを送るとします。受け側がその日3秒遅く応答したために送信側がリトライを行い、二重配信が起きて顧客に二通メールが行きサポートが混乱する。別の日にパートナーが障害を起こしてまったくリトライしなければ、「配達済み」が届かずダッシュボードが更新されないままになります。

Webhookの信頼性は「完璧な1回のリクエスト」ではなく、現実の混乱に対処できる設計です：リトライ、冪等性（idempotency）、後から再実行して確認できる仕組み。

3つの基本要素：リトライ、冪等性、再実行（replay）

Webhookには受信（inbound）と送信（outbound）の両方があります。受信Webhookは外部（決済プロバイダ、CRM、配送ツール）からあなたが受け取るコール、送信Webhookはあなたが顧客やパートナーへ送るコールです。どちらもあなたのコードに原因がない理由で失敗することがあります。

リトライは失敗後に起きることです。送信側はタイムアウト、500系エラー、接続切断、もしくは応答が遅いと判断したときに再試行します。良いリトライは稀な例外ではなく想定された動作で、受信側を過負荷にせず副作用を二重にしないのが目的です。

冪等性は重複を安全にする方法です。「二回受け取っても一度だけ実行する」という意味です。同じWebhookが再度届いたら検出して成功を返し、ビジネスアクションを二度実行しない（例えば請求書を二度作らない）ようにします。

再実行（replay）は回復のボタンです。バグ修正後やパートナーの障害後に、過去のイベントを意図的かつ制御された方法で再処理する機能です。リトライは自動で即時的、replayは意図的で数時間や数日後に行われることが多い点が違います。

Webhookの信頼性を目指すなら、いくつかの目標を決めて設計してください：

• 失われないイベント（受信または送信した試行をいつでも見つけられる）
• 安全な重複（リトライやreplayで二重請求や二重作成、二重メールが発生しない）
• 明確な監査トレイル（「何が起きた？」に素早く答えられる）

実務的には、すべてのWebhook試行をステータスと一意のidempotencyキーで保存するのが効果的です。多くのチームはこれを小さな「webhook inbox/outbox」テーブルとして実装します。

受信Webhook：再利用できる受信フロー

ほとんどのWebhook問題は送信側と受信側のクロックと実行環境が異なることから起きます。受信者としてのあなたの役割は予測可能であること：すばやく受理し、届いたものを記録し、安全に処理することです。

「受理」と「処理」を分ける

HTTPリクエストを速く保ち、本当の仕事は別の場所で行うフローを作ってください。これによりタイムアウトが減り、リトライのダメージも小さくなります。

• 速やかに受理する。リクエストが受け入れ可能なら速やかに2xxを返す。
• 基本チェックをする。Content-Type、必須フィールド、パースの検証を行う。署名があるならここで検証する。
• 生のイベントを永続化する。本文と必要なヘッダ（署名、イベントID）を受信タイムスタンプや「received」などのステータスと一緒に保存する。
• 作業をキューに入れる。バックグラウンド処理用のジョブを作り、2xxを返す。
• 明確な結果で処理する。副作用が成功したときだけイベントを「processed」にマークする。失敗したら理由と再試行が必要かどうかを記録する。

「速く応答する」の目安

現実的な目標は1秒未満で応答することです。送信側が特定のコードを期待しているならそれに合わせてください（多くは200、いくつかは202を好む）。送信側が再試行すべきでない場合は4xxを返します（例えば無効な署名）。

例：dbが高負荷のときにcustomer.createdのWebhookが届いても、このフローなら生のイベントを保存し、キューに入れて2xxで応答できます。ワーカーは後で再試行できますから送信側の再送は不要になります。

配信を壊さない受信時のセキュリティチェック

セキュリティチェックは重要ですが、目的は悪意あるトラフィックをブロックしつつ正当なイベントは遮らないことです。多くの配信問題は受信側が厳しすぎたり、誤ったレスポンスを返したりすることが原因です。

まず送信者を証明しましょう。署名付きリクエスト（HMAC署名ヘッダ）や共有シークレットヘッダを優先し、大きな処理を行う前に検証して、欠けているか間違っている場合はすぐに失敗させます。

ステータスコードの扱いに注意してください。リトライの動作を制御します：

• 認証失敗には401/403を返して送信側が永久にリトライしないようにする。
• JSONの不正や必須フィールドの欠落には400を返す。
• あなたのサービスが一時的に受け入れられない場合のみ5xxを返す。

IPの許可リストはプロバイダが安定したドキュメント化されたIP範囲を提供する場合に有効です。IPが頻繁に変わる、または大きなクラウドプールを使うプロバイダでは、許可リストが正当なWebhookを静かに落としてあとでしか気づかないことがあります。

プロバイダがタイムスタンプと一意のイベントIDを提供しているなら、replay保護が可能になります：古すぎるメッセージを拒否し、最近のIDを追跡して重複を検出します。タイムウィンドウは小さく保ちつつ、クロックのずれを許容する猶予を入れてください。

受信者向けの簡単なセキュリティチェックリスト：

• 大きなペイロードをパースする前に署名や共有シークレットを検証する。
• 最大ボディサイズと短いタイムアウトを設定する。
• 認証失敗や不正なスキーマには401/403や400を返し、受理したイベントには2xxを返す。
• タイムスタンプをチェックするなら、数分程度の猶予を許容する。

ログでは監査トレイルを残しつつ、敏感なデータを永久保存しないでください。イベントID、送信者名、受信時間、検証結果、生の本文のハッシュを保存します。ペイロードを保存する必要がある場合は保持期間を設け、メールアドレスやトークン、支払い情報などはマスクしてください。

助けになるリトライ設計

リトライは短期の問題を配信成功に変えるので有用です。一方でトラフィックを増幅したり本当のバグを隠したり重複を生んだりすると害になります。差は「何を再試行するか」「どのように間隔をあけるか」「いつ止めるか」を明確にすることです。

基準としては、受信側が後で成功する見込みがあるときだけリトライしてください。簡単な考え方は「一時的な障害は再試行、送信側の間違いは再試行しない」です。

実務的なHTTP結果の分類：

• 再試行する：ネットワークタイムアウト、接続エラー、HTTP 408、429、500、502、503、504
• 再試行しない：HTTP 400、401、403、404、422
• 場合により再試行：HTTP 409（重複か実際の競合かによる）

間隔の付け方が重要です。指数バックオフとジッターを使い、多数のイベントが同時に失敗してもリトライ嵐にならないようにします。例：5秒、15秒、45秒、2分、5分、そして各回に小さなランダムオフセットを加える。

再試行の最大ウィンドウと明確な打ち切りを設けてください。よくある選択は「最大24時間再試行する」や「最大10回まで」など。そこを超えたら配信問題ではなく復旧問題として扱います。

運用のためにイベント記録には次を必ず残してください：

• 試行回数
• 最後のエラー
• 次の試行時刻
• 最終ステータス（再試行をやめた場合はデッドレター状態）

デッドレターアイテムは検査しやすく、問題修正後に安全に再実行できるようにしておきます。

実務で使える冪等性パターン

冪等性は同じWebhookを何度受け取っても余計な副作用が起きないことを保証します。リトライやタイムアウトは起きるものなので、冪等性を取り入れるだけで信頼性が大きく上がります。

安定するキーを選ぶ

プロバイダがイベントIDをくれるならそれを使うのが最も簡単です。

イベントIDがない場合は、次のような安定したフィールドからキーを作ります（ハッシュなどで）：

• プロバイダ名 + イベント種別 + リソースID + タイムスタンプ
• プロバイダ名 + メッセージID

キーと受信時刻、プロバイダ、イベント種別、結果を一緒に保存してください。

一般的に効くルール：

• キーは必須扱いにする。作れないイベントは推測せず隔離する。
• キーはTTL（7〜30日など）を付けてテーブルが無限に増えないようにする。
• 処理結果も保存して、重複時に一貫した応答を返せるようにする。
• キーにユニーク制約を付け、並列の同時処理で二重実行されないようにする。

ビジネス処理自体も冪等にする

キーのテーブルがあっても、実際の操作自体が安全でなければ意味がありません。例：create orderのWebhookは、最初の挿入がタイムアウトした後に二つ目の注文を作ってしまわないように、外部の注文IDや外部ユーザーIDを使ってupsertするなどのパターンを使います。

順序が前後することはよくあります。user_updatedがuser_createdより先に届いた場合、event_versionが新しいときだけ適用する、あるいはupdated_atが既存より新しい場合のみ更新する、などのルールを決めてください。

ペイロードが異なる重複は最も厄介です。事前に方針を決めておきましょう：

• キーが一致するがペイロードが異なる場合はプロバイダのバグとしてアラートを上げる。
• キーが一致し、差分が無視できるフィールドだけであれば無視する。
• プロバイダを信用できないなら、ペイロード全体のハッシュを用いた派生キーに切り替え、競合は新しいイベントとして扱う。

目的は単純：現実世界の一つの変更が、一つの結果だけを生み出すこと。メッセージが三回届いても見かけ上は一度しか処理されない状態を作ることです。

回復のための再実行ツールと監査ログ

パートナーが不安定なとき、信頼性は完璧な配信よりも素早い回復にかかっています。replayツールがあれば「いくつかのイベントを失った」がルーチン作業に変わります。

まず各Webhookのライフサイクルを追うイベントログを作ってください：received、processed、failed、ignored。時間、イベント種別、関連IDで検索できるようにして、サポートが「注文18432に何が起きた？」に答えられるようにします。

各イベントに再実行に十分なコンテキストを保持してください：

• 生のペイロードとキーとなるヘッダ（署名、イベントID、タイムスタンプ）
• 正規化して抽出したフィールド
• 処理結果とエラーメッセージ（あれば）
• 当時使われたワークフロー／マッピングのバージョン
• 受信、開始、終了のタイムスタンプ

これがあれば、失敗したイベントに対して「Replay」アクションを追加できます。ボタン自体よりもガードレールが重要です。良いreplayフローは以前のエラー、再実行時に何が起きるか、安全に再実行可能かを表示します。

誤操作を防ぐガードレール例：

• 再実行前に理由を必ず記入させる
• 再実行権限を限られたロールに限定する
• 初回処理と同じidempotencyチェックを再実行時にも行う
• 再実行のレート制限を設けてインシデント中に新たなスパイクを作らない
• 書き込みを伴わない検証のみのドライランモードを用意する

インシデントでは複数のイベントが関係することが多いので、時間範囲での再実行（例：「10:05〜10:40の失敗イベントを再実行」）をサポートし、誰がいつなぜ再実行したかをログに残してください。

送信Webhook：監査できる送信フロー

送信Webhookは退屈な理由で失敗します：受信側が遅い、短時間の障害、DNSの問題、プロキシが長時間リクエストを切るなど。信頼性は各送信を追跡可能で再現可能なジョブとして扱うことから生まれます。単なる一度きりのHTTP呼び出しにしないでください。

予測可能な送信フロー

各イベントに安定した一意のイベントIDを付与してください。このIDはリトライやreplay、サービス再起動の間も同じであるべきです。試行ごとに新しいIDを生成すると受信側の重複排除やあなた側の監査が難しくなります。

各リクエストには署名を付け、タイムスタンプを含めてください。タイムスタンプは古いリクエストを拒否する助けになり、署名は転送中に改ざんされていないことを証明します。署名ルールは単純にしてパートナーが実装しやすいようにしてください。

配信の履歴はイベント単位ではなくエンドポイント単位で追跡します。同じイベントを三つの顧客へ送るなら、それぞれの送信先ごとに試行履歴と最終ステータスが必要です。

多くのチームが実装できる実務的なフロー：

• event ID、endpoint ID、ペイロードハッシュ、初期ステータスでイベントレコードを作る
• 署名、タイムスタンプ、idempotencyキーをヘッダに付けてHTTPリクエストを送る
• すべての試行（開始時刻、終了時刻、HTTPステータス、短いエラーメッセージ）を記録する
• タイムアウトや5xxに対して指数バックオフ＋ジッターでリトライする
• 明確な上限（最大試行回数または最大経過時間）を超えたら停止してレビュー用に失敗扱いにする

送信側でもidempotencyキーは重要です。受信側が最初のリクエストを処理したがクライアントが200を受け取れなかった場合、同じキーがあれば受信側は重複を明確に扱えます。

最後に、失敗を可視化してください。「失敗」は「喪失」ではなく「再実行できるように一時停止している」ことを意味するべきです。

例：不安定なパートナーとクリーンな復旧

サポートアプリがチケットの更新をパートナーに送って、彼らのエージェントが同じ状態を見られるようにしているとします。チケットが更新されるたびにticket.updatedのWebhookをポストします。

ある午後、パートナーのエンドポイントがタイムアウトを返し始めました。最初の配信はあなた側のタイムアウトに達して「到達したか不明」と扱われます。良いリトライ戦略ならバックオフを行いながら再試行し、同時にイベントは同じイベントIDでキューに残り、各試行が記録されます。

問題の本質：冪等性がないとパートナーが重複処理してしまいます。試行#1は彼らに届いて処理されたがレスポンスが返らなかったかもしれない。試行#2が後で到着すると二重に「チケットが閉じられた」処理が走り、二通のメールや二つのタイムラインエントリが発生します。

冪等性を使えば各配信にイベントID由来のidempotencyキーを付け、パートナー側は一定期間そのキーを保存しておき、重複時には「すでに処理済み」と返せます。あなたは想像で判断する必要がなくなります。

パートナーが復旧したらreplayで欠落した一回分の更新を直します。監査ログからイベントを選び、同じペイロードとidempotencyキーで一度だけ再実行すれば、既に受け取っている場合でも安全です。

インシデント中のログには次が明確に出るべきです：

• Event ID、チケットID、イベント種別、ペイロードのバージョン
• 試行番号、タイムスタンプ、次のリトライ時刻
• タイムアウトか非2xxか成功か
• 送ったidempotencyキーとパートナーが「duplicate」と報告したかどうか
• 誰が再実行したかと最終結果のreplayレコード

よくある間違いと落とし穴

多くのWebhookインシデントは一つの大きなバグではなく、小さな選択が積み重なって信頼性を壊します。

ポストモーテムでよく出る罠：

• リクエストハンドラ内で重い処理（DB書き込み、外部API呼び出し、ファイルアップロード）をして送信側がタイムアウト→リトライになる
• プロバイダが重複を送らないと仮定して二重請求や二重作成、二重メールを起こす
• 間違ったステータスコードを返す（受け付けていないのに200を返す、再試行しても意味のないデータで500を返す）
• 相関IDやイベントID、リクエストIDなしで出荷し、ログと顧客報告を突合するのに何時間もかかる
• 永遠にリトライする設計がバックログを作り、パートナーの障害を自分の障害に転化する

単純なルールが有効です：速やかに受理し、安全に処理する。受理に必要な検証だけを行い、保存（またはキュー）してから残りを非同期で処理してください。

ステータスコードは思ったより重要です：

• 2xxはイベントを保存（またはキューイング）して処理されると確信できるときのみ使う。
• 4xxは送信側が修正すべき入力エラーや認証失敗に使う。
• 5xxはあなた側の一時的な問題にのみ使う。

リトライの上限を設定してください。固定ウィンドウ（例：24時間）や固定試行回数で止めて「要レビュー」に移し、人間がreplayすべきか判断するようにします。

速攻チェックリストと次のステップ

Webhookの信頼性は習慣化が大きいです：速く受理し、積極的に重複排除し、注意深くリトライし、再実行パスを確保すること。

受信（Receiver）の速攻チェック

• リクエストを安全に保存したら速やかに2xxを返し（重い処理は非同期で）
• 受信したことを証明するのに十分なイベントを保存する（後でデバッグできるように）
• idempotencyキーを要求するか、プロバイダ＋イベントIDから導出してDBで強制する
• 署名不正やスキーマ不正には4xx、サーバの一時的問題には5xxを使う
• 処理ステータス（received、processed、failed）と最後のエラーメッセージを追跡する

送信（Sender）の速攻チェック

• 各イベントに一意のイベントIDを割り当て、試行間で安定させる
• すべてのリクエストに署名とタイムスタンプを付ける
• リトライポリシー（バックオフ、最大試行回数、打ち切り）を定義し守る
• エンドポイントごとの状態を記録する：最後の成功、最後の失敗、連続失敗数、次回試行時刻
• すべての試行をサポート・監査に十分な詳細でログに残す

運用では、どの範囲（単一イベント、時間範囲、ステータス別）をreplayするか、誰ができるか、デッドレターレビューの手順を事前に決めておきましょう。

最後に：これらをすべて手作業で配線せずに構築したければ、ノーコードプラットフォームのAppMasterを使うと実用的です。PostgreSQLでWebhookのinbox/outboxテーブルをモデル化し、Business Process Editorでリトライ・replayフローを作り、失敗イベントを検索して再実行できる内部管理パネルをノーコードで用意できます。