Webhook：实时加密支付通知

​

Webhook 如何工作？

1. 您在网关配置中设置 callback-url 和 webhook-secret。
2. 当事件发生时（例如检测到支付），网关构建一个 NotifyPayload 并发送到您的 URL。
3. 您的服务器验证 HMAC-SHA256 签名并处理事件。

​

Webhook 负载格式

​

有哪些 Webhook 事件类型？

​

订单事件

​

收款（结算）事件

​

签名验证

sign = HEX(HMAC-SHA256(JSON.stringify(data), webhook_secret))

​

投递保证

• 至少投递一次。 在极少数情况下，同一事件可能多次到达。使用 nonce 字段进行去重。
• 带退避的重试。 如果您的端点返回非 2xx 状态或超时，XPayLabs 会使用指数退避重试。
• 顺序性。 单个订单的事件按顺序投递。不同订单的事件可能乱序到达。

​

最佳实践

1. 始终验证签名。 在处理 Webhook 之前，务必验证 sign 字段。
2. 快速返回 200。 立即确认接收，然后异步处理事件。
3. 使用 nonce 去重。 存储已处理的 nonce 以安全处理重复投递。
4. 使用 ORDER_PENDING_CONFIRMATION 优化用户体验。 在交易完全确认之前，在 UI 中显示”检测到支付”。
5. 使用 ORDER_SUCCESS 进行履约。 这是交付商品或服务的信号。