Skip to main content
如果你的 Webhook 端点未返回 2xx 状态码,启润支付将自动重试投递。

重试计划

对于本文档中的订单和争议事件,启润支付最多进行 7 次投递:首次投递加 6 次重试。 等待时间从前一次投递失败时计算,实际投递可能稍晚。累计 7 次投递失败后,Webhook 被标记为失败并停止自动重试。

什么算作失败

以下情况 Webhook 投递被视为失败:
  • 你的端点返回非 2xx HTTP 状态码(如 400、500)
  • 你的端点在 10 秒内未完成响应
  • 无法连接到你的服务器(DNS 错误、连接被拒绝、超时)
2xx 响应(如 200、201、204)即被视为投递成功,不论响应体内容如何。

处理重试

由于 Webhook 可能被重试,你的端点应该是幂等的 — 多次处理同一事件应产生相同的结果。

使用事件 ID 去重

每个 Webhook 事件都有唯一的 id 字段。通过唯一约束持久化已处理的事件 ID,并在同一事务中提交业务变更和处理标记:
上述数据库方法用于说明事务要求,请按你的存储系统实现。业务操作也应以稳定标识保护,例如付款履约使用 order_id,退款使用 refund_id。争议更新不能仅按案件 ID 去重,因为一个案件可能产生多次更新。

快速返回 200

处理时间较长时,应先验证签名,将事件持久化到接收表或队列,再返回 200。工作进程随后处理并负责自己的重试。若持久化失败,请返回非 2xx 响应,让 Kyren 重试:

监控 Webhook 投递

排查投递问题时,请将 Kyren Webhook 事件与你自己的服务端日志对照。请记录:
  • 你配置的 Webhook URL
  • 事件类型和订单号
  • 你的服务端收到请求的时间
  • 你的服务端返回的响应码或错误
如果需要 Kyren 协助检查投递尝试,请带上这些信息联系支持。

故障排除