Vibe Coding 接收 Webhook：签名验证、去重收据与可恢复重试

AI 根据一份样例很容易写出 JSON.parse(req.body) 后更新订单的 handler，但真实 Webhook 具备四个不舒服的事实：请求来自公网、供应商会重复投递、事件可能乱序、你的进程可能在处理一半时崩溃。返回 200 只能说明本次 HTTP 被接受，不能证明业务状态已正确收敛。

Webhook 订阅正确性讨论发送端的端点验证和投递证明；接收端则要把“来源可信”“事件只影响一次”“失败可恢复”拆成三个独立门。给 AI 的上下文必须包含供应商当前官方签名格式，不能凭经验套用通用 HMAC 字段名。

先保留原始请求字节

签名通常覆盖原始 body，有时还包含时间戳或消息 ID。框架在验证前若已解析 JSON、改变空白或重新编码，计算出的摘要会不同。路由应先以受限大小读取原始字节，解析供应商定义的签名 header，按官方拼接规则计算 MAC，再用常量时间比较；验证通过后才解析内容。

密钥来自密钥管理系统，按 endpoint 或租户隔离，不写入代码和日志。轮换期间验证当前与上一代密钥，记录命中代际；旧代命中降到零并超过供应商最大重试窗口后再撤销。不能在多个候选密钥间提前返回导致明显时序差异，也不能用请求里的 endpoint ID 直接选择未授权租户密钥。

若协议含签名时间戳，校验与本地时钟的允许偏差，过旧请求拒绝以降低重放风险；服务器需监测时钟同步。时间窗不能代替事件去重，因为攻击者或供应商可在窗口内重放。GitHub 与 Stripe 的签名格式、header 和算法并不相同，实现必须逐供应商建立适配器和测试向量。

接受点只做持久化

验签、基本 envelope 校验后，在短事务中插入 event receipt，唯一键通常包含 provider、endpoint/account 与供应商事件 ID。receipt 保存类型、接收时间、载荷安全摘要、签名代际、处理状态和加密/受控的原始载荷引用。相同事件 ID 但载荷摘要不同应报警并隔离，不能覆盖第一次证据。

插入成功后提交并尽快返回供应商要求的 2xx；重复事件也返回成功，避免供应商持续重试。业务逻辑放入 worker。若 API 收据与队列发布不能原子完成，可在同一事务写 inbox 任务，再由轮询 worker 领取，或使用可靠 Outbox。这里与HTTP 幂等键正确性类似，但事件身份由供应商分配，作用域和载荷绑定仍需明确。

数据库临时不可用时不能先返回 2xx，因为事件尚未可靠接收；返回供应商认可的失败状态让其重试。验签失败、body 超限、格式错误则按协议决定永久拒绝，并对来源、频率与摘要做安全日志，绝不回显密钥或原始敏感载荷。

处理器要容忍重复与乱序

worker 以状态机处理 receipt，领取时带 lease，崩溃后可超时重领。每一步使用数据库约束或条件更新保证重复执行无害；向第三方发出副作用时稳定传递事件派生的幂等键。API 幂等设计可作为下游写入的基础，但不要把 receipt 标为完成后才执行不可恢复副作用。

事件到达顺序通常不等于业务版本顺序。若 payload 提供对象版本或发生时间，只在新版本高于已应用版本时更新；若事件只是“对象变了”的提示，收到后用服务端凭证拉取当前对象状态，再按版本写入。删除事件可能无法再查询，需要保存 tombstone。不要依靠接收时间覆盖状态，否则晚到的旧事件会把新状态倒退。

失败分为可重试与永久错误。网络超时、429 和 5xx 进入带上限的退避；未知提交结果先查询或用幂等键重试。schema 不支持、资源映射缺失或权限撤销进入隔离队列，保留原因和人工重放入口。重放使用原始事件 ID，不能创建“新事件”绕过去重。

No-code Webhook 工作流回放中的配置代际也值得借鉴：处理器版本、映射配置和解析 schema 写入 receipt，后续修复可明确选择按原版本重放还是迁移到新版本。

用对账覆盖永远没收到的事件

即使接收端完美，也可能因端点配置错误、供应商停投或长期故障漏事件。按供应商能力定期拉取权威对象或事件列表，以远端 ID/版本与本地状态对账；差异生成可审计修复任务。Webhooks 负责低延迟提示，对账负责最终发现缺口，两者不能互相替代。

验收测试使用官方文档给出的签名算法和固定测试向量，覆盖原始 body 被改一字节、错误密钥、过期时间、缺 header、双密钥轮换、重复 ID 同/异载荷。并发发送相同事件，断言只有一份 receipt 和一次业务效果；在提交 receipt 后、排队后、业务写后分别杀死 worker，恢复后最终状态一致。

再反序投递 created/updated/deleted、让旧版本晚到、制造 429 与超时，验证状态不倒退且重试有界。监控验签失败率、重复率、接收到持久化耗时、待处理年龄、重试次数、隔离数量和对账差异；按 endpoint 告警但控制高基数。

Webhook 可靠性不是在 handler 外包一层 try/catch。原始字节签名建立来源证据，唯一 receipt 建立接受证据，可重入 worker 建立处理证据，周期对账弥补投递缺口。把这四份证据和故障矩阵交给 AI，它才能生成可恢复的集成，而不是只在样例请求上成功一次。