接收 Webhook，不要把“收到请求”误当成“业务已经完成”

先确定四个可靠性边界

先确认适用边界和提供方真实承诺

这份指南适合接收支付结果、订单状态、物流进度、代码托管事件、电子签约结果和企业 SaaS 变更通知的团队。它解决的是外部系统主动推送事件后的接收与处理可靠性，不替代同步 API 的权限设计，也不保证跨两个独立系统天然实现强一致。

立项时逐项记录事件目录、负载版本、事件唯一标识、签名算法、时间戳、响应时限、成功状态码、自动重试周期、人工重发方式、事件查询接口和历史保留期。不要把一个平台的规则套给另一个平台：Stripe 明确提醒重复与乱序，并建议快速返回成功；GitHub 当前文档则说明失败投递不会自动重发，需要人工或程序主动处理。

如果某个关键动作不能接受延迟或漏失，应保留主动查询和业务对账能力。Webhook 可以降低轮询延迟，但不应成为唯一事实来源；订单、支付、库存等最终状态仍应以双方约定的权威系统和状态机为准。

• 为每个提供方建立接入卡片，保存官方文档链接、测试环境、生产端点、责任人和变更通知渠道。
• 把“事件送达”“本地接收”“业务处理”“外部副作用完成”拆成不同状态，禁止用一个成功标记代替全过程。
• 明确哪些状态允许自动推进，哪些金额、退款、发货或权限变化必须二次查询或人工确认。

在解析和执行业务之前完成签名与重放校验

接收层应读取服务商实际签名覆盖的原始字节，按官方算法计算摘要，并使用恒定时间比较函数核对签名。部分框架会先解析 JSON、改变空白或字符编码，这可能导致签名验证失败；因此原始请求体的获取方式必须在所用框架和网关上实际测试。

若协议包含签名时间戳，应同时检查时间窗口，降低旧请求被截获后再次提交的风险；窗口大小要结合提供方重试机制、网络延迟和服务器时钟同步确定，不照搬其他平台的默认值。请求体大小、内容类型、允许的事件类型和账号标识也应在进入业务队列前校验。

签名密钥放入专用密钥或配置系统，不写入代码、日志和错误响应。轮换时按提供方能力短暂同时接受新旧密钥，记录使用的密钥版本而不是密钥值；确认新密钥流量正常后再撤销旧密钥。IP 白名单可作为附加限制，但不能代替签名。

• 保存原始请求体哈希、事件标识、来源账号、签名版本、接收时间和校验结果，敏感负载按最小必要原则留存。
• 缺少签名、签名不匹配、时间戳过期、负载过大或事件类型未订阅时拒绝处理，并记录不含秘密的原因码。
• 用提供方测试向量或测试事件覆盖正常签名、正文被改、时间过期、新旧密钥并存和字符编码场景。

把可靠接收与耗时业务处理分成两个阶段

端点通过基础校验后，先在本地事件表或可靠消息入口中保存原始事件、规范化元数据和初始状态；只有确认持久化成功，才向提供方返回其认可的成功响应。发货、生成文件、调用下游、发送消息等耗时动作交给后台消费者，避免上游因超时发起更多重投。

这里的快速响应不等于先响应再落库。若事件尚未可靠保存，进程退出就可能留下无法察觉的缺口；如果持久化失败，应按提供方协议返回可重试结果，并由监控及时发现。若提供方不会自动重投，则必须通过其投递查询接口或定时拉取补回。

接收表至少应区分 received、processing、succeeded、retryable_failed 和 terminal_failed，并保存尝试次数、下一次执行时间、最后错误分类与处理版本。状态更新使用事务或条件更新，避免两个消费者同时取得同一事件。

• 接收路径只做必要校验、去重登记和可靠入队，不在请求线程中执行长事务或多级外部调用。
• 为接收入口设置独立的连接池、请求体上限、并发保护和过载策略，防止突发回调拖垮主业务。
• 确认响应必须遵循具体提供方文档；不要自行假设所有 2xx、3xx 或超时都会得到相同处理。

同时约束投递去重和业务副作用幂等

第一层去重用于识别同一投递事件，可在数据库中对“提供方、租户或端点、事件 ID”建立唯一约束。第二层幂等用于保护真实业务动作，例如以支付单和动作类型约束入账，以订单和履约批次约束发货；即使提供方产生两个不同事件 ID，业务唯一约束仍能阻止重复副作用。

不要依赖进程内缓存作为唯一去重手段，它会在重启、多实例扩容或过期后失效。事件状态与业务写入尽量放在同一数据库事务；如果必须调用外部服务，向下游传递稳定幂等键，并把调用前后状态与响应标识记录下来，避免网络断开后无法判断调用是否已成功。

HTTP 规范中的“幂等方法”描述的是重复相同请求的预期服务器效果；它不会自动让 Webhook 内部的发券、记账或通知变得幂等。业务团队仍需逐个列出副作用、唯一条件和重复执行时的返回结果。

• 唯一键写入与事件创建放在数据库约束中处理，不使用“先查询再插入”作为唯一防线。
• 重复事件返回已接收结果，但保留重复次数和最近投递时间，便于识别提供方异常或本地超时。
• 邮件、短信、优惠券、积分、库存和财务流水分别设计业务幂等键，不把一个事件 ID 当作所有动作的唯一语义。

按状态机处理乱序，不用到达顺序覆盖当前事实

网络重试、并发处理和提供方内部流程都会让事件乱序。收到“已完成”之后仍可能收到较早的“处理中”，因此不能按接收时间简单覆盖业务状态，也不能假设时间戳相同就代表同一个事件。

为业务对象定义允许的状态迁移和终态规则；事件若携带资源版本、递增序号或服务端更新时间，可把它作为条件更新依据。没有可靠版本字段时，对支付、退款、履约等关键对象主动查询提供方当前状态，再决定是否推进本地状态。无法自动判断的冲突进入人工队列，不静默丢弃。

事件负载格式也可能随 API 版本或端点配置变化。解析器要明确支持的版本和必需字段，对新增未知字段保持兼容，对缺少关键字段或无法识别的事件类型隔离告警；升级前用录制的脱敏样本做回归。

• 列出每类对象的合法状态迁移、不可逆终态、补偿动作和权威查询接口。
• 条件更新失败时记录实际版本与期望版本，不用无条件重试覆盖较新的业务状态。
• 保存解析器版本和负载版本，让历史事件在代码升级后仍可解释、重放或迁移。

让自动重试、隔离和人工重放都有停止条件

先把错误分为暂时性、永久性和需要人工判断三类。网络中断、限流或短暂依赖不可用可以指数退避并加入随机抖动；签名错误、字段不兼容和已撤销权限通常不能靠原样重试解决。达到次数或时间上限后，把事件移入隔离区并告警。

重放工具应默认只读预览，显示事件来源、业务对象、原失败步骤、已完成副作用和将要执行的处理版本。操作人需要选择从哪一步继续、是否跳过已完成动作，并留下原因、审批人、执行时间和结果。批量重放必须限速，可暂停，并先用少量样本验证。

不要把删除失败记录当成恢复，也不要编辑原始事件来“让它通过”。如确需修正映射或补充业务参数，保留原事件和修复记录，生成新的处理尝试，确保之后可以解释数据为什么发生变化。

• 为每类外部依赖配置最大并发、超时、退避、总尝试窗口和人工升级条件。
• 隔离区按错误类别、事件类型、租户和影响对象检索，并提供安全重放与永久关闭流程。
• 演练消费者崩溃、下游成功但响应丢失、乱序、重复、未知版本和批量积压，核对副作用没有重复。

用监控与定期对账发现“双方都以为成功”的缺口

监控至少覆盖验签失败率、接收延迟、入队失败、待处理数量、最老积压时间、重试与隔离数量、处理耗时和对账差异。告警要能定位到提供方、事件类型、租户和处理版本，但日志与指标标签不能包含密钥、完整负载或不受控的业务 ID。

对账任务按权威系统的时间游标或资源清单查询已完成对象，与本地状态比较，并为时间边界保留重叠窗口。差异分为本地缺事件、事件处理失败、状态乱序、外部动作未落地和本地成功但上游未确认；每一类都要有可审计的补偿路径。

上线采用影子接收、小流量事件类型、单租户或非关键动作逐步扩大。观察至少覆盖提供方完整重试窗口和业务结算周期；具体时长由所接平台与业务风险决定，不能用通用数字代替。

• 仪表盘能从业务对象追到事件、每次处理尝试、下游调用和最终状态，也能从失败事件反查受影响对象。
• 对账任务记录查询范围、游标、总数、差异数、补偿结果与下次起点，失败时不会跳过时间段。
• 在切换端点、轮换密钥、升级 API 版本或修改状态机后执行专项对账，并保留明确回退方案。