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

Webhook 配置与排障

配置

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

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

一、先看投递记录

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

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

最常见的两种：

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

三、修好之后重投

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

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

重试阶梯

投递失败（非 2xx、超时、连不上）后按这个阶梯退避，单位是分钟：

1 ─► 5 ─► 30 ─► 120 ─► 360 ─► dead

5 次等待 + 第 6 次投递；第 6 次再失败才转 dead 并在商户后台告警。超时是 10 秒。

⚠ 最后一次重试在约 8.6 小时之后。一次超过这个时长的故障会让事件

全部进 dead —— 那时只能靠 redeliver 补，而它要你自己列出来一条条补。

所以宁可先回 200 再异步处理，也不要让端点在故障期间一直拒。

成功判据是任意 2xx，响应体我方不解析 —— 你返回什么都不影响我方。

请求头

验签：

v1 == base64( HMAC-SHA256( webhook_secret, "<t>." + 原始请求体 ) )

⚠ t 要校验 ±300 秒容差，否则一个被截获的旧请求可以被无限重放。

⚠ 用原始字节做 HMAC，不要先反序列化再重新序列化 ——

键序或缩进变了签名就对不上，而这是 401 里最常见的一种。

你的端点该长什么样

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

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

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

⚠ 事件体只告诉你「变了」，不是账本事实。 收到之后回查对应的

详情端点，并按 status_version 向前合并 —— 事件与轮询的到达顺序没有保证。

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

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

相关

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