Webhookの再試行と手動リプレイ：安全な復旧設計

Webhookが失敗したときに何が壊れるのか

Webhookの失敗はたいてい「ただの技術的な不具合」ではありません。ユーザーからすると、アプリが何かを忘れたように見えます：注文が「保留」のまま、サブスクリプションが解除されない、チケットが「支払い済み」に移らない、配送ステータスが間違っている、などです。

多くの人はWebhook自体を見ていません。彼らが見るのは、あなたのプロダクトと銀行や受信箱、ダッシュボードの間で不整合が起きていることです。金銭が絡むと、そのギャップはすぐに信頼を壊します。

失敗は退屈な理由で起きます。エンドポイントが遅くてタイムアウトする。デプロイ中にサーバーが500を返す。ネットワークのホップでリクエストが落ちる。作業は終わっているのに遅れて応答してしまうこともあります。送信側から見るとどれも「配信されていない」扱いになるので、再試行するかイベントを失敗としてマークします。

復旧設計は重要です。Webhookイベントは取り消せない操作（支払いの完了、返金の発行、アカウント作成、パスワードリセット、発送など）を表すことが多く、イベントを逃すとデータが壊れます。逆に二度処理すると二重請求や二重作成が起きます。

だからWebhookの再試行と手動リプレイは単なるエンジニアリングの問題ではなく、プロダクトの判断です。選択肢は2つあります：

• プロバイダ側の自動再試行：送信側が成功応答を受け取るまでスケジュールに従って再送する。
• あなた側の手動リプレイ：サポート担当や管理者が何かおかしいと判断して再処理をトリガーする。

ユーザーは予期しないことなく信頼性を期待します。システムは多くの場合で自動的に回復すべきで、人が介入する場合は何が起きるか明確で、二回押しても安全であるべきです。ノーコードで作る場合でも、すべてのWebhookは「再到着する可能性がある」と扱ってください。

自動再試行：助かる場面と害になる場面

自動再試行はWebhookのデフォルトの安全網です。多くのプロバイダはネットワークエラーやタイムアウト時にバックオフを伴って再試行し、1〜2日後に打ち切ることが多いです。それは安心感がありますが、UXとサポートのやり取りを変えます。

ユーザー側では、再試行が「支払い確定」の瞬間を気まずい遅延に変えることがあります。顧客はプロバイダのページで成功を見ているのに、あなたのアプリは「保留」のまま次の再試行を待ちます。逆に、ダウンタイム後に再試行が一気に到着して古いイベントが一斉に "catch up" することもあります。

再試行がうまくいくとサポートのチケットは減ることが多いですが、残ったチケットは難しいものになります。単一の明白な失敗ではなく、複数回の配信、異なるレスポンスコード、元の操作と最終成功の間に長いギャップがあって、その説明が難しいのです。

ダウンタイムが遅延配信の大量発生を引き起こしたり、遅いハンドラが処理済みの作業でもタイムアウトを続けたり、システムが冪等でないために重複配信が二重作成や二重請求を誘発すると、運用上の痛みが現実になります。フラッキーな動作を隠してしまい、問題がパターン化することもあります。

再試行は、失敗処理が単純な場合に十分です：非金銭的な更新、二度適用しても安全なアクション、多少の遅れが許容されるイベントなど。イベントが金銭を動かしたり取り消せない記録を作る可能性がある場合、Webhookの再試行対手動リプレイは利便性ではなくコントロールの問題になります。

手動リプレイ：コントロール、説明責任、トレードオフ

手動リプレイは、人がWebhookイベントの再処理を決定することを意味します。サポート担当、顧客側の管理者、あるいは（低リスクの場合）エンドユーザーが「再試行」をクリックするケースもあります。手動リプレイはスピードよりも人のコントロールを優先します。

UXは賛否があります。高価値のインシデントでは、リプレイボタンは次の再試行を待たずに単一のケースを素早く直せます。しかし多くの問題は誰かが気づいて行動するまで放置されがちです。

サポートの負荷は通常増えます。リプレイは「静かな失敗」をチケットやフォローアップに変えるためです。利点は透明性：サポートは何がリプレイされたか、いつ、誰が、なぜを確認できます。金銭やアクセス、法的記録が絡む場合、この監査トレイルは重要です。

セキュリティが最も難しい点です。リプレイツールは権限と範囲を厳しくすべきです：

• 信頼された役割のみが、特定のシステムに対してリプレイを行える。
• リプレイは「全て再送」ではなく単一イベントに限定する。
• すべてのリプレイは理由、実行者、タイムスタンプをログに残す。
• UIでは機微なペイロードはマスクする。
• レート制限で乱用や誤操作を防ぐ。

手動リプレイは、請求書作成、アカウントプロビジョニング、返金、二重請求や二重作成を招く可能性のある高リスク操作に好まれます。また「支払いが確定したことを確認してから注文作成をリトライする」といったレビュー手順が必要なチームにも合います。

再試行とリプレイの選び方

自動再試行と手動リプレイのどちらを採るかに一律のルールはありません。一般的に安全なのは混合戦略です：低リスクイベントは自動で再試行し、金銭や取り返しの付かない重い処理は明示的なリプレイを要求する。

まず各Webhookイベントをリスクで分類します。配送ステータスの更新は遅れると迷惑ですが長期的な被害は少ない。一方で payment_succeeded や create_subscription のようなイベントは高リスクで、余分に処理されると二重請求や二重作成の可能性があります。

次に誰が復旧をトリガーできるかを決めます。システムによる自動再試行は安全かつ高速な操作に向きます。敏感なイベントはサポートやオペレーションが顧客のアカウントやプロバイダのダッシュボードを確認してからリプレイを実行する方がよいことが多いです。エンドユーザーにリプレイ権限を与えるのは低リスクの操作に限るべきで、さもないと繰り返しクリックで重複を生みます。

時間ウィンドウも重要です。再試行は一時的な問題を治す目的で分単位・時間単位で行われます。手動リプレイはより長く許容できますが、無期限にしてはいけません。一般的なルールはビジネス文脈がまだ有効な間（例：出荷前、請求期間が閉じる前）にリプレイを許可し、その後はより慎重な調整を要求することです。

イベントごとの簡易チェックリスト：

• もし二度実行されたら最悪何が起きるか？
• 誰が結果を検証できるか（システム、サポート、オプス、ユーザー）？
• どのくらいの速さで成功させる必要があるか（秒、分、日）？
• 許容できる重複率はどれくらいか（お金ならほぼゼロ）？
• インシデント1件あたりどれだけのサポート時間が許容されるか？

create_invoice を逃した場合は短い再試行ループで十分なことがあります。charge_customer を逃した場合は、監査トレイルと冪等性チェックを備えた手動リプレイを優先してください。

ノーコードツール（例：AppMaster）でフローを作るなら、各Webhookをビジネスプロセスとして扱い、低リスクステップは自動再試行、高リスクは確認を必要とするリプレイアクションに分けてください。リプレイ前に何が起こるかを表示し、二重クリックでも安全になるようにします。

冪等性と重複排除の基本

冪等性とは、同じWebhookを複数回処理しても結果が一貫していることを意味します。プロバイダが再試行しても、サポートがリプレイしても、最終的な結果は一度だけ処理した場合と同じであるべきです。これはWebhookの再試行と手動リプレイにおける安全な復旧の基礎です。

信頼できる冪等性キーの選び方

重要なのは「これを既に適用したかどうかをどう判断するか」です。送信者が提供するものによって良い選択肢が変わります：

• プロバイダのイベントID（安定して一意なら最良）
• プロバイダの配信ID（再試行の診断に有用だがイベントIDと同一とは限らない）
• あなたの複合キー（例：provider + account + object ID + event type）
• 生ペイロードのハッシュ（何もなければフォールバック。ただし空白やフィールド順に注意）
• あなたが生成してプロバイダに返すキー（対応するAPIがある場合のみ機能）

プロバイダが一意のIDを保証しないなら、ペイロードを唯一性の根拠として信用せず、ビジネス意味に基づく複合キーを作りましょう。支払いならchargeやinvoiceのIDとイベントタイプの組み合わせが考えられます。

重複排除をどこで行うか

一層に頼るのは危険です。安全な設計は複数のポイントでチェックします：Webhookエンドポイント（すぐに拒否する）、ビジネスロジック（状態チェック）、データベース（最終的な保証）。データベースは最終ロックとして、処理済みキーを一意制約付きのテーブルに保存しておけば、複数のワーカーが同じイベントを同時に適用するのを防げます。

順序の入れ替わりは別問題です。重複排除は重複を止めますが、古い更新が新しい状態を上書きするのは止められません。タイムスタンプ、シーケンス番号、または「常に前へ進める」ルールで対処します。例：注文が既にPaidなら、後から来た"Pending"更新は無視します。

ノーコード環境（例：AppMaster）では、processed_webhooks テーブルをモデル化し、冪等性キーに一意インデックスを付けます。ビジネスプロセスはまずレコード作成を試み、失敗したら処理を止めて送信元には成功を返します。

ステップバイステップ：デフォルトで安全なリプレイツール設計

良いリプレイツールは、問題発生時のパニックを軽減します。リプレイは同じ安全な処理経路を再実行し、重複を防ぐガードレールを備えているときに最も効果的です。

1) まず記録し、次に行動する

受信したWebhookは監査記録として保存してください。受け取った生のボディ、署名やタイムスタンプなどのキーとなるヘッダ、配信メタデータ（受信時刻、ソース、試行回数など）をそのまま保存し、正規化したイベント識別子も保持します。

署名は検証しますが、ビジネスアクションを実行する前にメッセージを永続化してください。処理が途中でクラッシュしても、元のイベントが残っていれば何が届いたか証明できます。

2) ハンドラを冪等にする

プロセッサは二度走っても同じ最終結果を出せるべきです。レコード作成、カード請求、アクセス付与の前に、そのイベントまたはビジネス操作が既に成功していないか確認します。

基本ルールは単純です：1イベントID + 1アクション = 1つの成功結果。先の成功があれば再度アクションを行わず、成功を返します。

3) 人が使える形で結果を記録する

リプレイツールは履歴が頼りです。処理ステータスとサポートが理解できる短い理由を保存しましょう：

• Success（作成されたレコードID付き）
• Retryable failure（タイムアウト、上流の一時的問題）
• Permanent failure（署名不正、必須フィールド欠落）
• Ignored（重複イベント、順序が古いイベント）

4) 「再作成」ではなくハンドラを再実行する

リプレイボタンは格納されたペイロードで同じハンドラを再キューするべきです。UIから直接「今すぐ注文を作る」のような書き込みを行うと重複排除をバイパスしてしまいます。

高リスクイベント（支払い、返金、プラン変更など）では、どのレコードが作成・更新され、どれが重複としてスキップされるかを示すプレビューを追加しましょう。

AppMasterのようなツールで構築するなら、リプレイアクションは管理画面から呼ばれても常に冪等ロジックを通るバックエンドのエンドポイントやビジネスプロセスとして実装してください。

サポートが素早く問題を解決するために何を保存するか

Webhookが失敗したとき、サポートができることはあなたの記録が明確である限り速くなります。唯一の手がかりが「500エラー」だけだと次のステップは推測になり、危険なリプレイにつながります。

良い保存設計は恐ろしいインシデントを日常のチェックに変えます：イベントを見つけ、何が起きたか確認し、安全にリプレイして何が変わったか証明するのです。

まずはすべての受信イベントに対して小さく一貫したWebhook配信レコードを持ち、ビジネスデータ（orders、invoices、usersなど）とは分けておきましょう。失敗を調査する際に本番データに触れずに済みます。

少なくとも次を保存してください：

• プロバイダ由来のEvent ID、ソース名、エンドポイント／ハンドラ名
• 受信時刻、現在のステータス（new、processing、succeeded、failed）、処理時間
• 試行回数、次回再試行時刻（あれば）、最後のエラーメッセージとエラータイプ／コード
• オブジェクトに紐づく相関ID（user_id、order_id、invoice_id、ticket_id）とプロバイダID
• ペイロードの取り扱い情報：生のペイロード（または暗号化されたBlob）、ペイロードハッシュ、スキーマ／バージョン

相関IDがあればサポートは有効に動けます。サポート担当が「Order 18431」で検索すれば、その注文に関係したすべてのWebhook（作成されなかった失敗も含む）を即座に見られるべきです。

手動操作の監査トレイルも残しましょう。誰がいつどこから（UI／API）リプレイしたか、結果はどうだったかを記録します。短い変更概要（例：「invoiceを支払済みにマーク」）を残すだけで紛争が大きく減ります。

保持期間を決めることも重要です。ログは最初は安価ですが、ペイロードに個人データが含まれることがあります。明確なルールを定めて守りましょう（例：生ペイロードは7〜30日、メタデータは90日など）。

管理画面は回答を明白にするべきです。イベントIDと相関IDで検索、ステータスや「対応が必要」フィルタ、試行とエラーのタイムライン、安全なリプレイボタン（確認と可視化された冪等キー付き）、内部インシデント用のエクスポートがあると便利です。

二重請求や重複レコードを避ける

Webhookの再試行と手動リプレイで最も危険なのは「再試行そのもの」ではなく、処理の副作用を繰り返すことです：カードを二度請求する、二重にサブスクを作る、同じ注文を二度出荷する、など。

安全な設計は「お金の移動」と「ビジネスの実行（フルフィルメント）」を分離します。支払いでは、ペイメントインテント作成（またはオーソリ）、キャプチャ、フルフィル（注文をPaidにする、アクセスを解放する、出荷する）のようにステップを分けます。Webhookが二度届いた場合、二度目は「既にキャプチャ済み」「既にフルフィル済み」を検知して停止できるのが理想です。

請求の作成時にはプロバイダ側の冪等性を利用しましょう。多くの決済プロバイダは同じリクエストに対して同じ結果を返すidempotency keyをサポートします。そのキーを内部の注文に保存しておき、再試行時に再利用します。

データベース内でもレコード作成を冪等にします。最も単純なガードは外部のイベントIDやオブジェクトID（charge_id、payment_intent_id、subscription_id）にユニーク制約を置くことです。同じWebhookが来たら挿入は安全に失敗し、既存レコードを読み込んで処理を続けます。

状態遷移に対しても前進のみ許すガードを入れます。例：注文をPendingからPaidにするのは、現在がPendingのときだけ。既にPaidなら何もしない。

部分的な失敗はよくあります：お金は成功したがDB書き込みが失敗した。これへの対処は、まず受信イベントの永続化を行い、その後処理する設計です。サポートが後でイベントをリプレイすれば、ハンドラが重複せずに欠けていたステップを完了できます。

それでも失敗した場合に備えて補償アクション（オーソリの取り消し、返金、フルフィルの取り消し）を定義しておきます。リプレイツールはこれらの選択肢を明示して、人が推測なしに結果を修正できるようにします。

よくある誤りと罠

多くの復旧計画が失敗するのは、Webhookを「もう一度押せるボタン」として扱うからです。最初の試行で既に何かを変えている場合、二度目はカードを二度請求したり重複レコードを作ったりします。

よくある罠の一つは、最初のペイロードを保存せずにリプレイすることです。サポートが後でリプレイするとき、今日作り直したデータを送ってしまい、実際に届いたメッセージと異なることがあります。これでは監査が壊れ、バグ再現が困難になります。

別の罠はタイムスタンプを冪等キーに使うことです。2つのイベントが同じ秒に発生することもあるし、時計がずれることもあります。冪等キーはプロバイダの一意イベントID（またはペイロードの安定した一意ハッシュ）に結びつけるべきで、時刻には依存しないでください。

サポートチケットに繋がるレッドフラッグ：

• 状態チェックなしに非冪等アクションを再試行している（例：「invoiceを作る」が既に存在しても再実行される）
• 再試行可能エラー（タイムアウト、503）と永久的エラー（署名不正、必須フィールド欠落）の区別がない
• 誰でも使えるリプレイボタン。権限チェックなし、理由欄なし、監査トレイルなし
• 実際のバグを隠す自動再試行ループが下流を攻撃し続ける
• 試行回数に上限がなく、同じイベントが繰り返し失敗しても人に通知されない

混在ポリシーにも注意してください。チームが両方の仕組みを無調整で有効にすると、同じイベントを別々のメカニズムが再送してしまうことがあります。

単純なシナリオ：支払いWebhookが到達したときにあなたのアプリが注文保存でタイムアウトしたとします。再試行が「顧客に再請求する」のではなく「既存の請求を確認してから注文をPaidにする」なら、厄介な事態は防げます。安全なリプレイツールは常に現在の状態を最初に確認し、欠けているステップだけを実行します。

出荷前の簡単チェックリスト

復旧は後回しにする機能ではなく、最初から組み込む機能です。常に安全に再実行でき、何が起きたか説明できるようにしましょう。

実用的な出荷前チェックリスト：

• ビジネスロジックを実行する前に、すべてのWebhookイベントを受信時に永続化する。生のボディ、ヘッダ、受信時刻、安定した外部イベントIDを保存。
• イベントごとに1つの安定した冪等性キーを使い、すべての再試行や手動リプレイでそれを再利用する。
• データベースレベルで重複排除を強制する。外部ID（支払いID、請求書ID、イベントID）に一意制約を置き、2回目の実行で別行が作られないようにする。
• リプレイは明示的で予測可能に。キャプチャや不可逆なプロビジョニングのようなリスクの高い操作には確認を要求し、何が起きるかを表示する。
• 受信から処理までの明確なステータスを追跡する：received、processing、succeeded、failed、ignored。最後のエラーメッセージ、試行回数、誰がリプレイしたかを含める。

完了と呼ぶ前にサポートの視点でテストしてください。誰かが1分以内に答えられるか：何が起きたか、なぜ失敗したか、リプレイ後に何が変わったか？

AppMasterでこれを作るなら、まずData Designerでイベントログをモデル化し、その後に冪等性を確認する安全なリプレイアクションを持つ小さな管理画面を追加してください。この順序で行えば「後で安全性を追加する」が「リプレイできない」に変わるのを防げます。

デプロイ戦略も早めに決めてください。クラウドかセルフホストかは運用に影響します。サポートが安全にログとリプレイ画面にアクセスでき、保持ポリシーが紛争解決に十分な履歴を残すことを確認してください。

例：支払いWebhookが一度失敗してから成功する場合

顧客が支払いを行い、プロバイダが payment_succeeded イベントを送ります。同時にあなたのDBが高負荷で書き込みがタイムアウトしたとします。プロバイダには500が返り、後で再試行します。

安全に回復するべき流れは次のとおりです：

• 12:01 イベントID evt_123 でWebhook試行#1が到着。ハンドラは INSERT invoice でDBタイムアウトにより失敗し、500を返す。
• 12:05 プロバイダが同じイベントID evt_123 を再試行。ハンドラはまず重複チェックテーブルを確認し、まだ適用されていないことを確認して請求書を作成し、evt_123 を処理済みとしてマークして200を返す。

重要なのは両方の配信を同じイベントとして扱うことです。請求書は1つだけ作成され、注文は1回だけ "Paid" に移り、顧客には領収書が1通だけ送られます。プロバイダが成功後にさらに再試行を送ることがあっても、ハンドラは evt_123 を既に処理済みと見てノーオペで200を返せばよいのです。

ログはサポートを安心させるものであるべきです。良い記録は「試行#1はDBタイムアウトで失敗、試行#2が成功、最終状態は適用済み」と示します。

サポートが evt_123 のリプレイツールを開くと退屈であるべきです："Already applied" を表示し、リプレイボタンを押しても安全チェックだけが再実行される。重複請求なし、重複メールなし、二重請求なし。

次のステップ：実用的な復旧フローを作る

受け取るWebhookイベントをすべて書き出し、低リスクか高リスクかをマークしてください。"User signed up" は通常低リスクです。一方で payment_succeeded、refund_issued、subscription_renewed は高リスクで、ミスが金銭の損失や面倒な巻き戻しを招きます。

その後、動作する最小限の復旧フローを作ります：すべての受信イベントを保存し、冪等なハンドラで処理し、サポート向けの最小限のリプレイ画面を公開する。目標は派手なダッシュボードではなく、次の質問に安全に答えられることです：「受信したか？処理したか？していないなら重複なしで再試行できるか？」

シンプルな最初のバージョン：

• 生のペイロード、プロバイダのイベントID、受信時刻、現在のステータスを永続化する。
• 同じイベントが二重に請求やレコードを作らないよう冪等性を強制する。
• 単一イベントを再実行するリプレイアクションを追加する。
• 最後のエラーと最後の処理試行を表示してサポートが何が起きたか分かるようにする。

それが機能したら、リスクレベルに応じた保護を追加してください。高リスクイベントは厳格な権限、明確な確認（例：「リプレイはフルフィルを引き起こす可能性があります。続行しますか？」）、誰がいつ何をしたかの完全な監査トレイルを要求します。

ノーコードで作りたいなら、AppMaster（appmaster.io）はこのパターンに適した実用的な選択肢です：Data DesignerにWebhookイベントを保存し、Business Process Editorで冪等なワークフローを実装し、UIビルダーで内部リプレイ管理画面を出荷できます。

デプロイを早めに決めてください。クラウドでもセルフホストでも、サポートが安全にログとリプレイ画面にアクセスでき、保持ポリシーが紛争解決に十分な履歴を保つことを確認してください。

まとめのチェックリスト（出荷前）

• 受信したWebhookイベントは必ず永続化する（生のボディ、ヘッダ、受信時刻、外部イベントIDを保存）。
• イベントごとに安定した冪等性キーを使い、すべての再試行と手動リプレイでそのキーを再利用する。
• データベース側での重複排除を強制する。一意制約により二度目の実行で別行が作られないようにする。
• リプレイは明示的で予測可能に。支払いのキャプチャや不可逆な操作は確認を要求する。
• 受信から適用までのステータスを追跡する（received、processing、succeeded、failed、ignored）。最後のエラー、試行回数、リプレイ実行者を含める。

最後に、サポートの質問をテストしてください：1分以内に「何が起きたか」「なぜ失敗したか」「リプレイ後に何が変わったか」を答えられるようにすること。

もしAppMasterでこれを作るなら、まずData Designerでイベントログを定義し、次にUIで安全なリプレイアクションを持つ管理画面を作ってください。これが「後で安全性を足す」が「安全にリプレイできない」になるのを防ぎます。

付録：安全に復旧する簡単な例

顧客が支払いを行い、プロバイダが payment_succeeded を送信したところ、あなたのDB書き込みがタイムアウトして500を返してしまったとします。プロバイダは evt_123 を再試行し、2回目で成功しました。

理想的な記録はこうです：試行#1はDBタイムアウトで失敗、試行#2が成功、最終状態は適用済み。サポートがリプレイを見ても「既に適用済み」と表示され、リプレイしても二重請求や重複メールは発生しません。

これを実現するには：

• 受信時にイベントを保存する
• 冪等性キーで重複を防ぐ
• データベースの一意制約で最終的な保証を得る
• リプレイは同じハンドラを通して実行し、プレビューや確認を加える

これだけでサポートは安心して操作できます。

最後に

すべてのWebhookをビジネスプロセスとして扱い、低リスクは自動再試行、高リスクは明確な手動リプレイで保護する設計が安全です。まずは受信を保存して冪等に処理し、サポート向けにシンプルで安全なリプレイ機能を用意してください。