Webhookの冪等性とリトライ:重複排除キー、保持期間、副作用の置き場所

要点: 多くの送信側はタイムアウトや5xxでリトライし、手動再送だけの所もあります。受信側はイベントごとに安定したキーを決め、副作用の前に処理状態を保存し、重複排除の記録を最長リトライ期間以上残します。完了済みのキーには2xxだけ返します。

Webhook受信のフロー図。冪等キーを照会し、完了済みなら2xxを返す。処理中なら待機またはコンフリクトのルールを適用する。新規なら先に永続化し、副作用を実行して完了にする。下の2本のタイムラインは送信側のリトライ期間と受信側の重複排除の保持期間を比べたもので、後者は前者以上の長さが必要。
図1. 副作用の前に重複排除の関門を置く。保持期間は送信側のリトライ期間をカバーすること。

1.0 送信側はリトライする。受信側は at-least-once を前提にする

こちらでタイムアウトしたWebhookが、実はもう処理済みということがあります。送信側にはそれがわからないので、もう一度送ってきます。500を返した場合も、単にネットワークが切れた場合も同じです。各イベントがちょうど1回届く前提で作ると、メールが二重に送られたり、在庫が二重に動いたり、1件の支払いにERP伝票が2枚できたりします。

どのくらいの期間リトライを続けるかはプロバイダーごとに違います。たとえばStripeは、本番環境のWebhook配信を指数バックオフで最大3日間リトライします。GitHubは失敗した配信を自動では再送しません。直近3日分の配信を、画面かAPIから手動で再送する形です。プロバイダーのリトライと再送の説明を読み、気にすべき最長の期間に合わせて重複排除の保持期間を決めてください。「すぐ応答しているからリトライは来ない」という見込みは当てになりません。

2.0 安定したキーを選ぶ

出どころよく使うキー補足
プロバイダーのイベントIDevt_…、配信GUID論理的なイベントごとに一意なら、まずこれを使う
複合キー(provider, event_id)1つのシステムで複数プロバイダーのWebhookを受ける場合
ヘッダーIdempotency-Key、X-GitHub-DeliveryIdempotency-Key は自社の外向きAPI向け。GitHubは再送時も X-GitHub-Delivery を変えないので、識別できるのは個々の試行ではなくイベント
業務オブジェクト(event_type, object_id)同じ変更に対してプロバイダーがEventオブジェクトを2つ出しうる場合に必要

キーは一意制約付きで保存します(またはアトミックな条件付き書き込み)。厄介なのは並行処理で、INSERTそのものを関門にしておかないと、2つのワーカーが両方とも「未登録」と判断してしまいます。

3.0 完了フラグではなく状態を持つ

状態意味同じキーが再度届いたとき
processing受け付け済み、処理中(任意でリース/オーナー)待つ、コンフリクトを返す、または進行中の処理に合流する。副作用の経路を2本目として始めない
completed永続化済み、副作用も完了すぐに2xxを返す。副作用なし
failed_retryable一時的な失敗。再試行して問題ないバックオフしながら再試行。キーは同じまま
failed_terminal人が対応しないと成功しないアラートを出す。自動で延々と回さない

processing は、そのキーを最初に受け付ける永続書き込みの中で一緒に記録します。メール、課金、ERP呼び出しのどれよりも前です。completed にするのは、それらの副作用が自分の永続記録を持ってから(または副作用を駆動するアウトボックスの行がコミットされてから)です。

4.0 リトライ期間と重複排除の保持期間

2つの期間をそろえる必要があります。

  1. 送信側のリトライ期間:プロバイダー(または自前の再送スクリプト)が同じイベントを再送しうる期間。
  2. 受信側の重複排除の保持期間:遅れて届いた重複を見分けるために、キーと結果を残しておく期間。

保持期間は、受け入れるリトライ期間 以上 でなければなりません。キーが先に期限切れになると、遅れたリトライは新しいイベントに見えます。手動再送はもっと前までさかのぼれます。Stripeの自動リトライは最長3日ですが、ダッシュボードからは15日、CLIからは30日以内のイベントを再送できます。保持期間が切れた後も運用担当がダッシュボードから再送するなら、保持期間を延ばすか、新しいキーと明示的な突き合わせの手順を必須にします。

5.0 応答する前に永続化する

困るのは次のケースです。ハンドラーは処理を終えたのに、送信側が2xxを受け取る前に接続が切れた。送信側はリトライします。成功をメモリ上でしか覚えていなければ、副作用がもう一度走ります。

書き込みの順番は次のとおりです。

  • まずイベント(またはアウトボックスの行)と processing/completed の状態を書く。
  • その書き込みがコミットされてから2xxを返す。
  • 冪等でない副作用は、重複排除の関門を通った後、永続レコードから動かす。
  • 副作用に時間がかかるなら、永続的に受け付けた時点で応答し、残りは非同期で片づける。その場合も同じキー、同じステートマシンのもとで扱う。

6.0 副作用は関門の後ろに置く

取り消しにくい処理、つまりメール送信、カード課金、ERP伝票の送信、チケット起票は、キーを確保してからでないと実行しません。completed のキーが再度届いた場合はこの経路を飛ばして成功を返します。相手側で副作用そのものが冪等でないなら、注文番号や請求書番号のような業務キーを別に持たせ、2回目の送信で伝票が2枚にならないようにします。

7.0 at-least-once 配信での順序

プロバイダーは順序を保証しないことがよくあります。updated が created より先に届くこともあれば、古いペイロードのリトライが新しいものの後に来ることもあります。冪等性だけではこれは直りません。業務オブジェクトごとにバージョン、シーケンス番号、updated_at のいずれかを持って古い書き込みを無視するか、ローカルの状態を変える前にプロバイダーから現在のリソースを取得します。

8.0 ログとアラートに残すもの

  • 重複排除ストアをキーでインデックスし、「evt_… はもう処理したか」が1回のクエリでわかるようにする。
  • 試行ごとにログを残す:キー、結果(重複/処理中/完了/失敗)、レイテンシ、試行回数。
  • 決済データや個人情報は共有のログに出しません。残すのはダイジェストと内部IDです。
  • リースを過ぎても processing のまま止まっているキーと、重複の急増(障害後に送信側がまとめてリトライしてくることが多い)にアラートを設定する。

決済、ERP、デバイスクラウド向けのWebhook受信側を作っている場合は、Web・クラウド・デバイス管理をご覧いただくか、プロジェクトのご相談からご連絡ください。

参考資料

よくあるご質問

プロバイダーは各イベントを1回だけ送ると言っています。それでも重複排除用のストアは要りますか。

実際の契約は多くの場合 at-least-once で、タイムアウト、5xx、ネットワークの瞬断のたびにリトライが走ります。同じペイロードがもう一度届いたときに副作用を二重に起こさないためには、安定したキーと、プロバイダーの最長リトライ期間をカバーする保持期間が必要です。

最初の処理がまだ終わっていないうちに重複が届いたら、何を返せばよいですか。

送信側のドキュメントに従って、コンフリクトか少し待つよう促す応答を返します。同じキーで副作用の経路を2本走らせることだけは避けてください。私たちは行をリース(オーナーと期限)付きで processing 状態にしておき、永続化と副作用が終わってから completed にしています。

処理済みのキーはどのくらい残しておくべきですか。

最低でも送信側の自動リトライ期間と同じ長さ、できれば公開されている手動再送の期間まで残します。キーが期限切れになった後に同じイベントが届くと、受信側は新しいイベントとして扱い、冪等でない処理をもう一度実行してしまうことがあります。

200を返したのに、メール送信やERP連携が実行されていませんでした。どう復旧しますか。

2xxを返す前にイベントと処理状態を永続化し、副作用はその永続レコードかアウトボックスから動かす形にします。書き込みが確定する前に成功を返すと、その後ローカルで失敗したときに復旧の手がかりが残らず、送信側は配信済みとみなしています。

イベントの順序が入れ替わって届くことがあります。冪等キーで解決できますか。

冪等キーが防ぐのは、同じイベントが二重に適用されることだけです。順序は別のルールで扱います。シーケンス番号や updated_at で古いバージョンを捨てるか、ローカルの状態を変える前にプロバイダーのAPIから現在のオブジェクトを取得します。