リソース · 54
Webhook: 繰り返し、遅延、およびリカバリの処理
受信した通知を、障害発生後も回復可能な、一意で追跡可能なビジネス効果に変換する。
更新済み · 19 min
このガイドが達成するのに役立つこと
- 通知を認証する
- レシートと処理を分離する
- 重複効果を防止する
- ブロックされたイベントを回復する
クイックチェック
- どのバイトが署名されているか?
- レシートはいつ永続的になるか?
- 2 つのワーカーが同時に動作できるか?
- プロバイダは順序を保証するか?
- 失われたイベントはどのように検出されるか?
手順
- 1
プロバイダ契約を読み込む
レコードのタイプ、バージョン、アカウントコンテキスト、署名、タイミング、再試行ルールを記録する。 Stripe は配信順序が保証されておらず、重複が発生する可能性があると述べている。 すべての API に Stripe 固有の遅延を適用しない。
納品物:日付付きプロバイダ契約。
- 2
効果発生前に検証する
プロバイダが必要とするライブラリと生のボディを使用して署名を確認する。 受け入れ可能なサイズとタイプを制限する。 認証済み環境で、秘密情報をログに記録せずに、無効な署名と予期しないアカウントコンテキストをテストします。
成果物:影響のない拒否。
- 3
確認応答の前に永続化します。
永続的な受信と低速な処理を分離します。 キューがイベントを受け入れられない場合、保持されたイベントとして報告しないでください。 成功は、契約に基づく受信を示すものであり、必ずしもビジネスアクションの完了を示すものではありません。
成果物:受信、処理中、完了、ブロック状態。
- 4
冪等性を強制します。
イベントキーとビジネス効果の同一性を定義します。 逐次配信だけでなく、同時繰り返しをテストします。 アトミック制約やロックを使用しない予備チェックでは、2つのワーカーが同じ効果を生み出す可能性があります。
成果物:効果の一意性の証拠。
- 5
遅延と無秩序を処理します。
古い通知が現在の状態を記述していると想定しないでください。 契約で許可されている場合はソースを参照し、検証済みのビジネス遷移を適用します。 解釈できないイベントは保持する。
成果物:遷移と逆順テスト
- 6
調整とリプレイ
所有者、原因、試行回数、および終了条件を含むエラーキューを準備する。 リプレイ中は重複保護を維持する。 プロバイダとアプリケーションを定期的に比較する。リカバリが成功したからといって、イベントが欠落していないとは限らない。
成果物:リカバリ手順と不一致レポート
再利用可能なワークシート
承認された観察結果を記入してください。 これらのフィールドは作業用テンプレートであり、観察結果ではありません。
| フィールド | 記録する情報 |
|---|---|
| イベント | プロバイダー、アカウント、識別子、バージョン |
| レシート | 検証済み署名と永続タイムスタンプ |
| 効果 | ビジネスキー、状態、一意性証明 |
| 復旧 | 原因、試行、所有者、終了 |
架空の事例
具体的な状況
架空の例です。顧客や実際の観測結果を示すデータではありません。 同じ決済通知が二度届き、一つの契約を二度有効化しようとしています。
決定と期待される証拠
通知の真正性を確認して重複を識別し、請求書と契約の状態を正当な情報源と照合します。 業務上の効果が一度だけ生じたことを確かめ、秘密情報を複写せず重複を記録します。HTTP応答だけでは正常な有効化を確認できません。
メカニズムの区別
| メカニズム | 目的 | 検証または制限 |
|---|---|---|
| 署名 | 契約に基づいてオリジンを検証する | 効果を一意にしない |
| 重複排除 | 繰り返し通知を認識する | 同時実行性とビジネスへの影響も確認する |
| 調整 | 欠落と差異を検出する | ソースと期間を指定する |
管理指標
| 指標 | 測定対象 | 最初のアクション |
|---|---|---|
| キューの経過時間 | 未完了イベントの遅延 | 最も古いイベントを検査する |
| 重複効果 | 誤って繰り返されたビジネスアクション | 正しいアトミック性 |
| ソース/アプリケーションのギャップ | 存在しない状態または異なる状態 | クロージャエビデンスとの調整 |
よくある間違い
- 署名ボディ検証前の解析
- 永続的な受信前の確認応答
- 順序付き配信を想定する
- 重複を順次のみテストする
よくある質問
HTTPの成功は処理完了を意味するのか?
契約によります。 非同期処理の場合、永続的な受信を意味するはずですが、ビジネス状態は別途追跡されます。
1回限りの納品を前提とできるか?
実際の契約に基づき、固有の効果と調整を考慮した、繰り返しや障害発生時の設計を行う。
本体全体を保持すべきか?
適切なアクセス権限と保持期間が確保された、必要な場合にのみ保持する。 最小限の痕跡は、機密情報を保持することなく、診断と復旧を支援するものでなければならない。
冪等性とAPI再試行の契約
この言語版の詳しい参照メモは英語で提供しています。
Separate request retries from notification repeats
An outgoing API request key, a received-event identifier and a business-effect identity serve different roles.
- Define provider, account, event and effect before selecting a deduplication key.
- Test concurrent workers and an unknown external-effect outcome.
- Reconcile business state with the source; a valid signature does not make processing unique.
Compare idempotency contracts →
References reviewed · RFC 9110 · §9.2.2, §10.2.3 · RFC 6585 · §4 · Stripe
Webhook:署名と再送
この言語版の詳しい参照メモは英語で提供しています。
Authenticate a delivery, retain the event and control its effect
A webhook signature answers a specific question: do the received bytes match those authenticated with the expected key? It guarantees neither freshness nor uniqueness nor successful business processing. Separate these decisions in the receipt contract so that the integration can be observed and recovered.
The signature and recovery rules below belong to the cited Stripe and GitHub contracts. The timeline and ten cases are fictional exercises; this page activates no endpoint, real secret or payment mechanism. Use official libraries and test the relevant provider configuration for a real integration.
Stripe and GitHub: six differences to retain
| Control | Stripe | GitHub |
|---|---|---|
| Signature header | Stripe-Signature contains t and one or more v1 signatures. The documented active scheme is v1. | X-Hub-Signature-256 contains a SHA256 HMAC prefixed with sha256=. |
| Authenticated message | Text timestamp, a period and the raw body: timestamp + "." + body. | The raw delivery body. Transport headers are not added to this HMAC message. |
| Freshness and replay | The timestamp is authenticated. Documentation states a five-minute default tolerance in its libraries; each retry receives a new timestamp and signature. | The body HMAC alone provides no freshness proof equivalent to Stripe’s timestamp. Plan duplicate detection and recovery according to the contract. |
| Identity to track | event.id identifies repeated delivery. Stripe also describes distinct events that may require correlation using data.object.id and event.type. | X-GitHub-Delivery identifies the delivery; requested redelivery retains that identifier. Its value remains outside the body authenticated by the HMAC described here. |
| Delivery failure | Live-mode automatic retries for up to three days with exponential backoff. A manual resend does not automatically cancel these retries. | GitHub does not automatically redeliver failures. Arrange manual redelivery or application-managed recovery using the available APIs. |
| Fast acknowledgement | Return a 2xx quickly, before lengthy work. Durable receipt before acknowledgement is the architectural policy of our exercise. | Respond with 2xx within ten seconds according to the documentation. A queue separates receipt from business processing. |
Retain three separate identities
| Identity | Fictional example | Purpose and limit |
|---|---|---|
| Transport attempt | delivery_attempt_02 | One event can arrive several times. An attempt’s timestamp and signature are not a business key. |
| Provider event | provider + account + environment + evt_training_001 | Recognise the same event within its scope. Define retention and recovery behaviour; a bare identifier without context may be insufficient. |
| Business effect | tenant_7 + case_42 + initial_activation | Prevent a second initial activation here. The key belongs to this operation; do not discard all future object updates by reducing them to the object identifier alone. |
Three bodies, six HMACs: what reformatting changes
Public exercise-only key: training-only-key-not-a-secret. Fixed timestamp: 1792663200, corresponding to 2026-10-22 at 10:00:00 UTC. Strings use UTF-8 with no trailing newline. A and B represent the same JSON object but have different bytes; C changes case_42 to case_43.
| Body | UTF-8 bytes | Exact string, written as a JSON string |
|---|---|---|
| A | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_42\"}" |
| B | 73 | "{\"id\": \"evt_training_001\", \"type\": \"evidence.ready\", \"object\": \"case_42\"}" |
| C | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_43\"}" |
| Body / scheme | Message used | Calculated hexadecimal HMAC-SHA256 |
|---|---|---|
| A · GitHub | body | d6ac0a608c901617782f3b7aef64198718e3affd410a219b22b84da008235364 |
| A · Stripe v1 | timestamp + "." + body | 0ad9c9f7c0df2d8a8265113e641d92f57ce0dffd703a7cf9f13c4163e21bf6dc |
| B · GitHub | body | c9c47b1432282b9a3c2cbf4aded2c750deed235ac948dffe248488b84a4af73d |
| B · Stripe v1 | timestamp + "." + body | 0ad8e262a5870766d4cce864f50a5feac65a3004e3c3208184da9cc075c7abd6 |
| C · GitHub | body | 55162fc08e3cb0efd0eb082978ba61a88cf3624ffc5322f19ab73d91466a616d |
| C · Stripe v1 | timestamp + "." + body | d7f4014489a900399a7049daa3e8f1ce2b208bf95b93c43492cb68f7d6f1b791 |
These results use the documented message constructions with a publicly displayed key and invented data. They are not authentic Stripe or GitHub deliveries. Different JSON serialization, even if semantically equivalent, must not replace the original body before verification. In production, compare in constant time and manage key rotation according to the selected library and contract.
Stripe tolerance parameter: the value 0 disables recency checking in the libraries described by its documentation. It does not mean “accept only the exact second”. Do not transfer the OAuth/OIDC example’s clock policy to this parameter.
Seven records for one local effect
Fictional scenario on 2026-10-22, all times UTC. Authenticate before admission and persist receipt before responding. An atomic constraint protects initial activation in the same database as its business state. Counts below are calculated for this exercise and describe no client outcome.
| UTC time | Observed signal | Scenario decision | Cumulative local effects |
|---|---|---|---|
| 10:00:00 | evt_training_001 admitted; response lost | Durable receipt, pending state; no business effect executed yet. | 0 |
| 10:00:01 | Worker A claims the event | Atomic work reservation; processing state. | 0 |
| 10:00:01 | Worker B sees the same event | Do not create a second processing owner or execute again. | 0 |
| 10:00:02 | Worker A commits the local transaction | Atomically write initial activation and its completed state. | 1 |
| 10:00:03 | New delivery of evt_training_001 | Authenticate the new attempt, find the completed event and acknowledge without a second effect. | 1 |
| 10:00:04 | evt_training_002 targets the same initial activation | Retain the distinct event; this business-operation key already exists. | 1 |
| 10:00:05 | evt_training_003 carries an earlier state | Reject a regressive transition under the exercise policy and reconcile the source. | 1 |
The transaction described protects a local effect. It does not make an external service call atomic. After an unknown external result, retain uncertainty, query the source and apply the available idempotency mechanism before retrying. A transactional outbox can organise emission; it does not establish a universal exactly-once guarantee.
Ten denial and recovery tests to prepare
01 · Invalid signature: no effect
Present a delivery whose HMAC does not match the received body.
Expected: reject before admission and any effect. Retain a redacted reason and configuration version, without recording the key, token or sensitive body content.
02 · Reformatted JSON with the original signature
Replace A with B while keeping the signature computed for A. Both JSON strings decode to the same object.
Expected: verification failure. Capture the raw body at the right framework stage; do not try different reformattings to recover the signature.
03 · Correct signature, stale timestamp
In a Stripe test, authenticate a 09:50:00 timestamp while the acceptance-test clock is 10:00:00, with a configured five-minute tolerance.
Expected: reject freshness despite a correct HMAC. Separate message integrity, delivery age and event creation age.
04 · Same event, newly authenticated attempt
Receive two deliveries of the same event.id; the Stripe retry has its own timestamp and signature.
Expected: authenticate each attempt, then find durable state. A different signature does not justify a second business effect.
05 · Two events, one initial activation
Receive two event identifiers requesting the same fictional initial activation of case_42.
Expected: record both events and protect this operation with its business key. Do not apply this rule blindly to legitimate successive updates of the same object.
06 · Two workers at the same instant
Start two workers on the same pending item in the authorised test environment.
Expected: atomic acquisition and one effect transaction. “Read absent, then insert” without a constraint can allow both workers through; inspect business results, not logs alone.
07 · Queue unavailable before acknowledgement
Simulate queue or database failure before receipt has been durably confirmed.
Expected under our architecture: do not acknowledge as though the event were retained. Exercise the provider’s recovery strategy; GitHub does not automatically redeliver failures.
08 · Response lost after durable receipt
Drop the response after notification persistence; let processing continue under the exercise policy.
Expected: the next attempt finds pending, processing or completed state. The sender may not know receipt succeeded; network uncertainty must not duplicate the effect.
09 · Old event after a newer state
Deliver a notification with an earlier state after a newer notification.
Expected: apply permitted business transitions and reconcile current state when necessary. A fresh signing timestamp can carry an old event; it does not prove business-state novelty.
10 · Manual recovery overlaps automatic retry
Send manual recovery and Stripe automatic retry towards the same event.
Expected: both paths use the same concurrency and idempotency controls. A successful manual resend does not itself cancel automatic retries; verify closure with the provider.
Six useful operating records
- Dated provider contract: environment, account, type, version, signature, timing and recovery.
- Redacted admission trace: internal reference, verification result, clock and policy version.
- Durable event state, work owner and evidence that the uniqueness constraint was tested.
- Effect identity and legitimately repeatable operations; separate the event from the business object.
- Failure queue with cause, attempt count, owner, next action and verified closure.
- Source/application reconciliation over a defined period, including never-received notifications and uncertain external effects.
Provider contracts and primary sources
- Stripe · Webhooks · Living documentation · reviewed 2026-10-22
Event delivery behaviors · Handle duplicate events · Verify manually · Preventing replay attacks - Stripe · Manage webhook endpoints · Living documentation · reviewed 2026-10-22
Process undelivered events · Resolve signature verification errors - GitHub · Validating webhook deliveries · Living documentation · reviewed 2026-10-22
HMAC-SHA256 · X-Hub-Signature-256 · raw payload · constant-time comparison - GitHub · Best practices for using webhooks · Living documentation · reviewed 2026-10-22
Respond within 10 seconds · X-GitHub-Delivery · redelivery retains the identifier - GitHub · Handling failed webhook deliveries · Living documentation · reviewed 2026-10-22
No automatic redelivery · manual or application-managed recovery
Sources reviewed on
APIエラー:型・状態・証拠
この言語版の詳しい参照メモは英語で提供しています。
An error response establishes neither failure nor safe replay
After interruption or an inconsistent response, a call may have produced an effect. Problem Details improves description; it does not prove no processing occurred or provide a universal retry policy.
- Preserve HTTP status, received body and permitted operation identifier in controlled traces.
- Check business state and idempotency rules before repeating an action.
- Test public messages without exposing secrets, internal paths or account details.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5
公式参照文献
参照文献はメソッドを裏付けるものです。 チェックは状況に合わせて調整してください。 これらは認証ではありません。 元の参照文献のタイトルやソース文書は別の言語で書かれている場合があります。
参照資料の確認日 .
- Stripe — Webhooks
- Stripe — Process undelivered webhook events
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457
- IETF · RFC 9110 — Retry-After et idempotence HTTP
- IETF · RFC 6585 — 429 Too Many Requests
- AWS Builders’ Library · Timeouts, retries, and backoff with jitter
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
