Webhook配信の重複を排除する

業務処理の冪等性にはイベントIDを使用してください。自動再試行は両方のIDを再利用しますが、手動の再配信では同じイベントIDと完全に同じペイロードを保持しながら、意図的に新しい配信IDを作成します。

手順

1. 生の本文に対してX-Dosya-Signatureを検証し、X-Dosya-Event-Idを読み取って、本文の最上位のidと一致することを確認してください。値がない場合や一致しない場合は不正な入力として扱います。
2. データベーストランザクションを開始し、一意制約のあるテーブルにイベントIDを挿入します。通常のログにペイロードを公開せず、イベントの種類、最初の配信ID、受信時刻、処理状態を保存してください。
3. 挿入が競合した場合は既存レコードの確定を確認してから2xxを返します。X-Dosya-Delivery-Idが異なるという理由だけで後続の変更を再適用しないでください。
4. 挿入に成功した場合は、同じトランザクションまたは原子的な処理で状態変更を適用し、冪等性レコードを確定します。副作用とその記録の間でクラッシュすると重複が起こり得ます。この設計はその隙間を防ぎます。
5. 診断用に各配信IDを試行ログに保持してください。自動再試行では元の配信IDを保持します。再配信は新しいwhd_…値を作成しますが、元のevt_…イベントIDをコピーします。
6. 受信側で1回失敗させ、再試行を待ってから、その行で再配信を使用してください。すべてのリクエストを追跡でき、共通のイベントIDに対して業務テーブルが正確に1回だけ変更されることを確認します。

dosyaのイベントIDは発行されたイベントごとに1回生成されます。1つのイベントが複数の購読エンドポイントに配信される場合があるため、イベントに基づく重複排除は、誤って複数回登録された受信側も保護します。

期待される結果

最初の検証済みイベントが後続の処理を1回確定します。自動試行と手動でキューに入れた再配信には、その処理を重複させずに2xx応答が返され、配信IDは運用上の追跡に利用できます。

重複が引き続き発生します。 一意のイベントIDの取得と業務上の変更が同じトランザクションにあるか確認してください。「後で処理済みにする」別の書き込みは、変更後に失敗する場合があります。

手動の再実行が意図せず無視されました。 すでに完了したイベントでは正しい動作です。オペレーターが本当に2回目の処理を意図する場合は、新しい業務コマンドを作成してください。

関連ガイド

• Webhook署名を検証する
• 配信を確認する