Webhook: 繰り返し、遅延、およびリカバリの処理

このガイドが達成するのに役立つこと

• 通知を認証する
• レシートと処理を分離する
• 重複効果を防止する
• ブロックされたイベントを回復する

クイックチェック

• どのバイトが署名されているか？
• レシートはいつ永続的になるか？
• 2 つのワーカーが同時に動作できるか？
• プロバイダは順序を保証するか？
• 失われたイベントはどのように検出されるか？

手順

1. 1

   プロバイダ契約を読み込む

   レコードのタイプ、バージョン、アカウントコンテキスト、署名、タイミング、再試行ルールを記録する。 Stripe は配信順序が保証されておらず、重複が発生する可能性があると述べている。 すべての API に Stripe 固有の遅延を適用しない。

   納品物：日付付きプロバイダ契約。

2. 2

   効果発生前に検証する

   プロバイダが必要とするライブラリと生のボディを使用して署名を確認する。 受け入れ可能なサイズとタイプを制限する。 認証済み環境で、秘密情報をログに記録せずに、無効な署名と予期しないアカウントコンテキストをテストします。

   成果物：影響のない拒否。

3. 3

   確認応答の前に永続化します。

   永続的な受信と低速な処理を分離します。 キューがイベントを受け入れられない場合、保持されたイベントとして報告しないでください。 成功は、契約に基づく受信を示すものであり、必ずしもビジネスアクションの完了を示すものではありません。

   成果物：受信、処理中、完了、ブロック状態。

4. 4

   冪等性を強制します。

   イベントキーとビジネス効果の同一性を定義します。 逐次配信だけでなく、同時繰り返しをテストします。 アトミック制約やロックを使用しない予備チェックでは、2つのワーカーが同じ効果を生み出す可能性があります。

   成果物：効果の一意性の証拠。

5. 5

   遅延と無秩序を処理します。

   古い通知が現在の状態を記述していると想定しないでください。 契約で許可されている場合はソースを参照し、検証済みのビジネス遷移を適用します。 解釈できないイベントは保持する。

   成果物：遷移と逆順テスト

6. 6

   調整とリプレイ

   所有者、原因、試行回数、および終了条件を含むエラーキューを準備する。 リプレイ中は重複保護を維持する。 プロバイダとアプリケーションを定期的に比較する。リカバリが成功したからといって、イベントが欠落していないとは限らない。

   成果物：リカバリ手順と不一致レポート

再利用可能なワークシート

承認された観察結果を記入してください。 これらのフィールドは作業用テンプレートであり、観察結果ではありません。

メカニズムの区別

管理指標

よくある間違い

• 署名ボディ検証前の解析
• 永続的な受信前の確認応答
• 順序付き配信を想定する
• 重複を順次のみテストする