判断の出発点
通知の到着と業務処理の完了は別です。再送と順序の入れ替わりを想定します。Stripeも同社のWebhookについてこの挙動を説明しています。他の提供元はそれぞれの契約を確認してください。
具体例で考える
架空の「請求支払済み」通知を検証し、IDと予定する仕事を保存し、永続的に受け付けてから応答します。再送なら同じ通知と認識し、二重に入金を記録しません。後の処理で失敗したら再試行できる状態を残します。
選択肢とその負担
Inboxは受信イベント、Outboxは自社トランザクションが生んだ仕事を記録します。保存された意図と通信を分ける仕組みです。定期照合は通知がエラーを伝えなくても両側の不一致を発見します。
見落としやすい点
IDをプロセスのメモリだけに残したり、業務更新の確定前に完了扱いしたりしないことです。古い通知は状態や版で判断します。一時障害は間隔を空け、恒久的に不正なデータは無限再試行せず人へ渡します。
配送イベントと業務の識別子を分ける
イベントIDと請求書参照を保存します。別々のイベントが同じ請求書を扱うため、一度見た請求書の全通知を拒むと正当な変更を失います。一方、同じ通知で二度入金処理してもいけません。受領キーと業務状態の制約を決め、実際の変更と一緒に確認を確定します。
仕事を受け入れる前に、提供元が文書化した方法で送信者を検証します。生の本文を署名する方式なら、JSONを再作成せず受信バイトを保ちます。署名秘密はログやソースへ入れません。検証、再送、保持期間は提供元ごとの契約で、別サービスの実装コピーは誤った対象を確認しかねません。
厄介な瞬間の障害復旧を示す
受信後、永続受理後、業務変更中にワーカーを止め、再起動後の受信箱と業務記録を確認します。外部作用はローカル結果保存前に受理されているかもしれません。対応していれば冪等性や照会を使い、単なるローカル状態で「必ず一回」を保証しないようにします。
運用者の管理された再試行は元のIDと理由を保持します。恒久的に無効な入力は無限再送せず例外へ回します。一定期間の正規記録を照合し、担当、緊急差異の扱い、解決の証拠を決めます。所有者のいないキューはデータを守っても、業務停止に誰も気づかない状態になり得ます。
依頼前に確認すること
同じ通知を繰り返しても効果は一回か。ワーカーが落ちても続けられるか。一件を調べ安全に再実行できるか。これを連携の受入実演に含めます。