配端点、验签、重投、排障 —— 收不到事件时按这一页的顺序查。

Webhook 配置与排障

配置

在商户后台的「开发者中心 → Webhook」里填端点地址。沙盒与生产各配一份 ——投递按环境过滤，配错环境的表现是「一条都收不到」，而不是收到别人的。

收不到事件？按这个顺序查

一、先看投递记录

GET /v1/webhooks/deliveries返回每一次投递的结果。三种情况：

二、没有投递记录 = 这个事件不属于你

最常见的两种：

• 事件类型没订阅。我方只发你订阅了的类型。
• 那笔业务不属于你的商户。跨商户的事件不会投递 —— 这是隔离，不是故障。

三、修好之后重投

POST /v1/webhooks/deliveries/{id}/redeliver

重投用的是原来那条事件体，z-event-id 不变 ——所以你的去重逻辑必须按 z-event-id 判，否则重投会被你自己丢掉。

你的端点该长什么样

1. 立刻读出 z-event-id，查一次「处理过没有」
2. 处理过 → 直接回 200（别再处理一遍）
3. 没处理过 → 落库、回 200、异步去做后续

⚠ 不要在回 200 之前做耗时的事。我方超时 10 秒，超时会重投 ——

而你那边其实已经处理成功了。表现是同一笔业务被处理两次。

⚠ 验签失败就回 401，别回 200。 回 200 等于告诉我方「收到了」，

那条事件不会再来 —— 而你其实一个字都没处理。

相关

• Webhook 概览 —— 事件体形状与验签算法
• 签名调试器 —— 逐字符比对签名串