本阶段课程
  1. EVM、合约、ABI 与状态
  2. Solidity 与本地合约测试
  3. ethers v6 与合约调用
  4. JSON-RPC、回执、事件与重组
  5. 链上索引与 GraphQL
  6. 预言机、价格来源与时效
  7. 合约权限、升级与安全验收
  8. DApp 发布、监控与重试
  9. 交易前端状态机 · 从点击到业务完成
  10. 合约发版验收 · 部署证据与角色交接
  11. 链上数据分析 · 事件、口径与数据延迟
  12. Solidity 事件实训 · 业务状态与索引字段
  13. Webhook 回调 · 签名核验、重复和乱序
  14. 事件索引表 · 原始记录、业务读模型与重建
本篇目录

阶段 03 · 第 13 / 14 课

Webhook 回调 · 签名核验、重复和乱序

学完能做到:为支付或索引通知设计可靠的接收与重放。

先看一个场景

应用分别收到「已支付」和「已退款」通知,但因为前一条重试,已支付事件最后才送达。若后台每次把订单直接改成回调中的状态,一个已经退款的订单会退回已支付。

处理步骤

  1. 按服务规范校验通知来源、签名与时效。部分签名方案需要保留原始请求内容。
  2. 原样保存可审计字段,按提供方事件 ID 或业务定义的唯一键记录。对回调尽快确认接收,再由队列执行业务核对。
  3. 使用已有订单和可确认状态决定是否合法推进。事件顺序无法确定时查询原服务状态。
  4. 给发货、退款和通知使用各自的幂等键。重放应能复算证据,避免重复外部动作。
  5. 记录接收时间、原始事件时间和处理结果。定期对账查漏,而不只监控回调成功率。

用一张表跟踪「收到了」和「处理完了」

商家系统在 10:05 收到已支付通知 E1,保存后回复接收成功,交给队列处理。10:20 收到 E2,查到订单已退款。10:22 又收到 E1,说明提供端重新投递了旧通知。三次送达只涉及两份不同的业务事件。

到达时点 记录什么 订单要怎样
10:05 E1 验明来源,保留事件 ID 与待处理动作 以订单证据确认已支付,并准备一次履约
10:20 E2 保存退款事件及原订单关系 状态更新为退款结果
10:22 E1 记录重试,复用原处理结果 保持退款状态,避免再次发货

Webhook就是外部服务主动发出的通知。它可用于尽快知道可能有变化,决定状态还要核对订单和事件是否匹配。若确认接收后内部没有处理完,要能从持久化记录恢复。仅看接口返回成功率找不到这类漏单。

动手练习

给事件 E1、E2、E1 依次标上支付、退款、重复支付。预期退款后的订单保持终态,重复回调记录为已见。再模拟服务确认接收后队列宕机,恢复时从持久化待处理记录继续。

自测

同一事件重复三次,是否要以最后一次投递时间更新订单阶段?

查看参考答案

投递时间有助于跟踪服务健康。订单阶段根据合法业务迁移及可信状态推进,重复投递只需更新接收记录或核对是否已处理。

Stripe Webhook 文档中的签名和重复事件示例

记录本课进度

完成练习后标记。进度保存在当前浏览器。

搜索课程