Webhook配信保証

Webhookは、HTTP （S）を介した非同期のSystem-to-Subscriber通知です。ネットワークは信頼性がありません。応答が失われ、パケットが重複しているか、順不同です。したがって、配信保証は「over TCP」ではなく、webhookプロトコルとドメインIDのレベルで構築されます。

主な目標は、（必要に応じて）キーによる注文で最低1回の配達を提供し、購読者に特異な処理と復元のための調整ツールを提供することです。

1）保証レベル

最善の努力-レトラなしの1回限りの試み。「重要でない」イベントでのみ使用できます。
少なくとも1回（推奨）-重複および注文切れが可能ですが、加入者が合理的な時間内に利用可能であることが条件でイベントが配信されます。
効果的に正確に一度（エフェクトレベルで）-契約者/送信者側のidempotencyとdedupストレージの組み合わせによって達成されます。「正確に一度」HTTPトランスポートは不可能です。

2） Webhookの契約： 最低必要

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

受信者の要件：署名をバッファして検証した後、迅速に'2xx'応答し、非同期に業務処理を行います。

3）秩序と因果関係

キーの順序： 保証は1つの'partition_key'（例えば。'player_id'、 'wallet_id'、 'psp_tx_id'）

グローバル注文は保証されていません。
送信側にはキーによるシリアル化のキュー（1つのコンシューマ/シャーディング）があり、受信側には'（source、 event_id）'の受信トレイがあり、オプションで'seq'が見つからないのを待っています。

ギャップが重要な場合-プルAPI 'GET/イベントを提供しますか？「catch up and consult」のためのafter=checkpoint'。

4） Idempotencyと重複除外

各Webhookは安定した'X-Webhook-Id'を持っています。
受信者は'inbox （event_id）'を格納します：PK-'source+event_id'；繰り返し→no-op。
副作用（データベース/ウォレットへの書き込み）は、イベントが最初に「見た」ときに1回だけ実行されます。
エフェクトを持つコマンドの場合は、Idempotency-Keyと結果キャッシュを使用して、リトレイウィンドウの期間を設定します。

5） Retrai、バックオフおよび窓

• '5xx/timeout/connection error/409-Conflict （retryable ）/429'にリトレインします。
• '409/423/429'を除いて'4xx'を引いてはいけません（そして一貫性のあるセマンティクスでのみ）。
• 指数関数バックオフ+フルジッタ：0。5s、 1s、 2s、 4s、 8s、……'max=10-15分'まで；TTLリトレイウィンドウ：例えば、72時間。
• 受信者からの「再試行後」を尊重します。
• 共通の締め切りがあります：「イベントを配信されていないと認識する」とDLQに転送します。

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6） DLQ#redrive

DLQ-完全なメタ情報（ペイロード、ヘッダー、エラー、試み、ハッシュ）を含む有毒イベントまたはTTL期限切れイベントの「墓地」。
オプションのエンドポイント/シークレット編集でredrive（ポイント再配信）のためのWeb コンソール/API。
レート制限redriveとバッチredriveの優先順位付け。

7）安全性

mTLS（可能であれば）またはTLS 1。2+.

1.ヘッダーから'（タイムスタンプ）を抽出し、スライディングウィンドウをチェックします（例えば、± 5分）。

8）クォータ、レート制限および株式

テナント/加入者ごとのフェアキュー：1人の加入者/テナントが全体のプールを獲得しないようにします。
発信トラフィックとエンドポイントごとのクォータとバースト制限。
'429'への反応：名誉'Retry-After'、トロールストリーム；長期的な制限-劣化（重要なイベントタイプのみを送信）。

9）サブスクリプションライフサイクル

登録/検証：POSTエンドポイント→チャレンジ/レスポンスまたは帯域外確認。
リース（オプション）：署名は'valid_to'まで有効です。延長-明示的。
シークレットローテーション：'current_secret'、 'next_secret'-'switch_at'。
テストping：主なトピックをオンにする前にルートをテストする人工イベント。
健康サンプル：レイテンシーとTLSプロファイル検査を伴う定期的なHEAD/GET。

10）スキームの進化（イベントバージョン）

バージョン管理イベントタイプ：'payment。承認されました。v1'→'……v2'。
Evolution-additive（新しいフィールド→MINOR APIバージョン）、breaking→a new type。
スキーマレジスタ（JSON-Schema/Avro/Protobuf）+提出前に自動検証。
bodyの「X-Event-Type」ヘッダーと「schema_version」フィールドは両方とも必要です。

11）観察可能性およびSLO

• 'deliveries_total'、 '2xx/4xx/5xx_rate'、 'timeout_rate'、 'signature_fail_rate'。
• 'attempts_avg'、 'p50/p95/p99_delivery_latency_ms' （2xxにパブリッシュ）。
• 'dedup_rate'、 'out_of_order_rate'、 'dlq_rate'、 'redrive_success_rate'。
• 'queue_depth'、 'olest_in_queue_ms'、' throttle_events'

• 配達のシェア≤ 60 s （p95）-99です。重要な出来事のための5％。
• DLQ ≤ 0。24時間で1％
• シグネチャの失敗≤ 0。05%.

'event_id'、 'partition_key'、 'seq'、 'attempt'、' endpoint'、'tenant_id'、'schema_version'、'trace_id'。

12）送信者参照アルゴリズム

1.トランザクションアウトボックスにイベントを書き込みます。
2.partition_keyとseqを定義します。キュー。
3.ワーカーはキーで取得し、リクエスト、サインを形成し、タイムアウト（接続/読み取り）で送信します。
4.'2xx'では、配信済みとして認識し、レイテンシとseq-checkpointを修正します。
5.'429/5xx/timeout'-ポリシーに従って後退します。
6.TTL→DLQとアラートで。

13）参照プロセッサ（受信機）

1.リクエストを受け付け、TLS/protoを確認してください。
2.署名と時間ウィンドウの検証。
3.Fast ACK 2xx（ローカル受信トレイ/キューへの同期書き込み後）。
4.非同期ワーカーは'inbox'を読み込み、'event_id'（祖父）をチェックします。必要に応じて'seq' inside 'partition_key'で注文します。
5.エフェクトを実行し、調整のために「offset/seq checkpoint」を書き込みます。
6.エラーの場合-ローカルリトレイ；「毒性」タスク→アラート付きのローカルDLQ。

14）調整（プールループ）

• 'GET/events？partition_key=...&after_seq=...&limit=...'-すべてのミスを与えるために。
• トークンのチェックポイント：'seqの代わりに'after=opaque_token'。
• Idempotent redelivery：同じ'event_id'、新しい't'の同じ署名。

15）有用な見出しとコード

2xx-受け入れられます（ビジネス処理が後であっても）。
410 Gone-エンドポイントが閉じられます（送信者は配信を停止し、サブスクリプションを「アーカイブ」としてマークします）。
409/423-リソースの一時的なブロック→リトレイは合理的です。
429-あまりにも頻繁に→スロットルとバックオフ。
400/401/403/404-構成エラー；レトライを止めてチケットを開けて。

16）複数のテナントおよび地域

テナント/エンドポイントごとの個々のキューと制限。
データ常駐：地域からデータを送信する。エンドツーエンドのヘッダ'X-Tenant'、 'X-Region'。
失敗の分離：1人の加入者の落下は残りに影響を与えません（別のプール）。

17）テスト

契約テスト：ボディ/署名の固定例、検証チェック。
カオス：ドロップ/重複、シャッフル順序、ネットワーク遅延、'RST'、 'TLS'エラー。
負荷：バーストストーム、測定p95/p99。
セキュリティ：アンチリプレイ、古いタイムスタンプ、間違った秘密、回転。
DR/リプレイ：分離されたスタンドでDLQからマスredrive。

18）プレイブック（ランブック）

1.成長'signature_fail_rate'

時計のドリフト、期限切れの「許容差」、秘密の回転を確認してください。一時的に「デュアルシークレット」を有効にします。

2.キューは老化しています（'oldest_in_queue_ms'）

作業者を増やし、重要なトピックの優先順位付けを可能にし、一時的に「騒々しい」タイプの頻度を減らします。

3.ストーム'429'で加入者

試行間のスロットリングと一時停止を有効にします。重要度の低いイベントタイプをシフトします。

4.質量'5xx'

特定のエンドポイントのための開いた遮断器、延期するために及びバッチを転換して下さい；購読者へのシグナル。

5.DLQの入力

非クリティカルなパブリッシングを停止し、低いRPSでバッチredriveを有効にし、サブスクリプションオーナーにアラートを送信します。

19）典型的なエラー

2xxレスポンス→リトレイと重複への同期重い処理。
body/timeウィンドウ署名→置換/リプレイの脆弱性がありません。
'event_id'と'inbox'→の不在をidempotentにすることはできません。
「グローバル注文」→「永遠のキューロック」の試み。
ジッタ/リミットなしで後退→インシデントの激化（雷の群れ）。
すべての加入者のための単一の共通のプール→「騒々しい」皆を置く。

20）売り上げ前のチェックリスト

• Contract： 'event_id'、 'partition_key'、 'seq'、 'event_type。vN'、HMAC署名とタイムスタンプ。
• 送信者：outbox、キーによるシリアライズ、バックオフ+ジッタ、TTL、 DLQとredriveでリトレイ。
• 受信者：受信トレイへのクイック書き込み+2xx；idempotent処置；ローカルDLQ。
• セキュリティ：TLS、署名、アンチリプレイ、デュアルシークレット、回転。
• クォータ/リミット：テナント/エンドポイントごとのフェアキュー、respect 'Retry-After'。
• APIとチェックポイントを調整する。購読者のためのドキュメント。
• Observability： p95/threads/errors/DLQ、 'event_id'にトレースします。
• イベントバージョニングとスキーマの進化ポリシー。
• インシデントプレイブックとグローバルポーズ/デフロストボタン。

お知らせいたします

信頼できるWebhookはHTTP上のプロトコルであり、単なる「POST with JSON」ではありません。"明確な契約（ID、オーダーキー、署名）、idempotency、ジッタ付きリトレイ、フェアキュー、デバッグされたプレイブックは、ベストケースを予測可能で測定可能な配信メカニズムに変えます。最低1回+キー順序+調整を作成すると、システムはネットワーク、ロードピーク、およびヒューマンエラーを冷静に生き残ります。