工作原理
- 事件发生(如客户完成付款)
- 启润支付向你配置的 Webhook URL 发送 HTTP POST 请求
- 请求中包含用于验证的签名
- 你的服务器验证签名、持久化事件,并在 10 秒内返回
200 - 工作进程幂等处理已持久化的事件,并负责自己的重试
配置 Webhook
在商户控制台中设置你的 Webhook 端点:- 前往 控制台 > 开发者 > Webhook 设置
- 输入你的 Webhook URL(如
https://yoursite.com/webhooks/kyren) - 复制你的 Webhook 密钥 — 用于验证签名
Webhook 载荷
每个 Webhook 请求包含以下请求头:
请求体是一个 JSON 对象:
最佳实践
验证签名
始终验证
X-Kyren-Signature 请求头以确保 Webhook 的真实性。参见 Webhook 签名验证。快速返回 200
验证签名并持久化事件后再返回
200。持久化失败时返回非 2xx,让 Kyren 重试。处理重复事件
使用事件
id 进行去重。由于重试机制,你的端点可能会收到同一事件多次。使用消息队列
异步处理时,将事件保存到持久化接收表或队列,保存成功后才确认。Kyren 收到
2xx 后,工作进程需要负责自己的重试。下一步
事件类型
查看所有事件类型
签名验证
验证 Webhook 签名
重试机制
了解重试行为