Skip to main content
Webhook 允许启润支付在付款或退款成功时向你的服务器发送通知。支持的事件及可选争议通知见事件类型。

工作原理

  1. 事件发生(如客户完成付款)
  2. 启润支付向你配置的 Webhook URL 发送 HTTP POST 请求
  3. 请求中包含用于验证的签名
  4. 你的服务器验证签名、持久化事件,并在 10 秒内返回 200
  5. 工作进程幂等处理已持久化的事件,并负责自己的重试

配置 Webhook

在商户控制台中设置你的 Webhook 端点:
  1. 前往 控制台 > 开发者 > Webhook 设置
  2. 输入你的 Webhook URL(如 https://yoursite.com/webhooks/kyren)
  3. 复制你的 Webhook 密钥 — 用于验证签名
你的 Webhook URL 必须:
  • 使用 HTTPS(生产环境必须)
  • 可公开访问
  • 持久化成功后,在 10 秒内完成 2xx 响应

Webhook 载荷

每个 Webhook 请求包含以下请求头: 请求体是一个 JSON 对象:

最佳实践

验证签名

始终验证 X-Kyren-Signature 请求头以确保 Webhook 的真实性。参见 Webhook 签名验证。

快速返回 200

验证签名并持久化事件后再返回 200。持久化失败时返回非 2xx,让 Kyren 重试。

处理重复事件

使用事件 id 进行去重。由于重试机制,你的端点可能会收到同一事件多次。

使用消息队列

异步处理时,将事件保存到持久化接收表或队列,保存成功后才确认。Kyren 收到 2xx 后,工作进程需要负责自己的重试。

下一步

事件类型

查看所有事件类型

签名验证

验证 Webhook 签名

重试机制

了解重试行为