Webhook 签名验证与幂等处理

Webhook 用于通知合作方后端异步业务状态变化。由于通知可能重试，接收端必须先验证签名，再把数据作为可信内容解析，并且以幂等方式处理事件。

Webhook 请求头

timestamp + nonce + rawBody

重建签名内容时必须使用 HTTP 接收的原始请求体。先解析再重新序列化 JSON 可能改变空格或字段顺序，从而产生不同的签名。

验证流程

1. 读取 timestamp、nonce 和 signature 请求头。
2. 保存未经修改的原始请求体。
3. 拼接 timestamp + nonce + rawBody。
4. 使用合作方 API Secret 计算 HMAC-SHA256。
5. 使用恒定时间比较方式对比计算结果与收到的签名。
6. 按已确认的接入策略检查时间有效性和 nonce 是否重复。
7. 验证成功后再解析并处理事件。

如果官方 Agent SDK 已提供验证器，应优先使用，避免长期维护独立签名代码。

订单幂等

建议保存的幂等记录

保存足够的信息，以识别重复通知并支持安全恢复：

条件允许时，应在同一事务中提交业务变更和幂等记录。收到重复事件时返回已有处理结果，不要再次修改余额、订单或用户状态。

超时与重试规则

HTTP 超时不能证明原请求失败。再次操作前，应使用原始 agentOrderNo 查询状态，或等待对应 Webhook。每次超时后都创建新的业务订单号，可能造成重复资金变动。

生产环境检查

• 在 JSON 解析或业务处理前验证签名。
• 分别保留原始请求体和解析后的数据。
• 按已确认的接入策略拒绝过期或重复请求。
• 确保重复和乱序事件不会造成错误业务结果。
• 记录事件 ID、合作方订单号、处理结果和请求时间。
• 从日志和支持附件中移除密钥和完整签名。

相关文档