资源 · 54
Webhook:处理重复、延迟和恢复
将收到的通知转换为唯一、可追溯的业务影响,以便在发生故障后恢复。
已更新 · 18 min
本指南有助于实现的目标
- 验证通知
- 将收据与处理分离
- 防止重复影响
- 恢复被阻塞的事件
快速检查
- 哪些字节已签名?
- 收据何时持久?
- 两个工作进程可以同时执行操作吗?
- 提供商是否保证顺序?
- 如何查找丢失的事件?
分步指南
- 1
读取提供商契约
记录类型、版本、账户上下文、签名、时间安排和重试规则。 Stripe 声明不保证交付顺序,并且可能会出现重复;不要对每个 API 应用 Stripe 特有的延迟。
交付物:带有日期的提供商契约。
- 2
在生效前进行验证
使用提供商要求的库和原始正文检查签名。 限制接受的大小和类型。 在授权环境中测试无效签名和意外的帐户上下文,且不记录密钥。
交付成果:无影响的拒绝。
- 3
确认前持久化
将持久化接收与缓慢处理区分开来。 如果队列无法接受事件,则不要将其报告为已保留。 成功表示已根据您的合约收到,但不一定表示业务操作已完成。
交付成果:已接收、正在处理、已完成和已阻塞状态。
- 4
强制幂等性
定义事件键和业务效果标识。 测试并发重复,而不仅仅是顺序交付。 在没有原子约束或锁定的情况下进行初步检查,可能会允许两个工作进程创建相同的效果。
交付成果:效果唯一性的证据。
- 5
处理延迟和混乱
不要假设旧的通知描述了当前状态。 在合约允许的情况下,查阅源并应用已验证的业务转换。 保留尚无法解释的事件。
交付物:转换和逆序测试。
- 6
协调和重放
准备一个包含所有者、原因、尝试次数和关闭信息的错误队列。 在重放期间保持重复保护。 定期比较提供程序和应用程序:成功恢复并不证明没有遗漏任何事件。
交付物:恢复程序和差异报告。
可重复使用的工作表
填写您已授权的观察结果。 这些字段是工作模板,而非观察结果。
| 字段 | 待记录信息 |
|---|---|
| 事件 | 提供商、帐户、标识符和版本 |
| 收据 | 已验证的签名和持久时间戳 |
| 影响 | 业务密钥、状态和唯一性证明 |
| 恢复 | 原因、尝试、所有者和关闭 |
虚构示例
示例情境
虚构示例:数据不代表客户或实际观察结果。 同一付款通知到达两次,处理流程尝试为同一个订阅开通两次。
决策及预期证据
验证通知真实性,识别重复,并将账单及订阅状态与权威来源核对。 确认业务效果只发生一次,记录重复时不复制机密。HTTP确认本身不能证明开通正确完成。
区分机制
| 机制 | 目的 | 验证或限制 |
|---|---|---|
| 签名 | 根据合同验证来源 | 不使效果唯一。 |
| 去重 | 识别重复通知 | 同时检查并发性和业务影响 |
| 协调 | 查找遗漏和差异 | 命名来源和周期 |
管理指标
| 指标 | 衡量内容 | 首要行动 |
|---|---|---|
| 队列年龄 | 未完成事件的延迟 | 检查最旧的事件 |
| 重复效果 | 错误重复的业务操作 | 纠正原子性 |
| 源/应用程序差距 | 缺失或不一致的状态 | 与闭合证据协调 |
常见错误
- 在签名体验证之前进行解析
- 在持久接收之前进行确认
- 假设按顺序交付
- 仅按顺序测试重复项
常见问题解答
HTTP 成功是否意味着处理完成?
这取决于合约。 对于异步处理,它应该意味着持久接收,而业务状态则单独跟踪。
是否可以假定只交付一次?
在实际合同下,针对重复交付和交付失败进行设计,并考虑其独特的影响和协调机制。
是否应该保留全部交付数据?
仅在必要时保留,并采用适当的访问权限和保留策略。 应尽可能减少追踪信息,以支持诊断和恢复,同时避免泄露机密信息。
幂等性与 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
