engineering

Webhook 可靠性：支付系统的生存指南

为什么你的 webhook 投递系统需要重试策略、签名密钥、死信队列和手动回放 UI——以及如何在不破坏 exactly-once 语义的前提下把这些都交付出去。

2026年4月1日12 min read作者：Kaadxpay 工程团队

Webhook 是任何支付平台调试得第二多的集成面（仅次于"为什么我的出款没结算？"）。它看起来简单——出事时往客户给的 URL POST 一个 JSON——但生产现实充满讨厌的边界 case。

下面是经过实战检验的清单，能帮你交付一个能扛住真实客户集成的 webhook 系统。

为什么 webhook 难

基本问题：你在调用你不掌控的代码，跑在你不掌控的基础设施上，经过别人的网络。每个假设都得做防御性设计。

会出错的事情：

客户的端点会在某次发布时挂 4 小时
客户的端点会返回 200 但消息被丢了
客户的端点响应太慢，你的客户端超时，你不知道对方收到没
客户的端点先返回 503、重试时返回 200，客户端处理了同一个事件两次
客户的端点被换掉，新端点不认你旧的签名密钥
客户的 WAF 静默丢掉你的 IP
客户的 TLS 在某个周六过期

朴素的"发出去就完事"webhook 实现，对上述大多数情况都束手无策。生产级实现能处理。

不可妥协的功能清单

任何支付级 webhook 系统都需要：

at-least-once 投递，带明确重试策略
每个请求体都做 HMAC 签名
稳定的 event ID，让接收方能去重
永久失败投递的 死信队列（DLQ）
手动回放 UI
客户能看到的 每个端点健康指标
真实可用的 IP 白名单文档
合理的超时（我们用 5s，其他人用 10-30s）
零停机的密钥轮换
版本化的事件 schema，能演进

如果你的设计缺了任何一项，你会过得很糟。

重试策略

最容易出错的地方。两种失败模式：

太激进。 每 5 秒重试一次持续 24 小时。客户端点恢复时被你的重试雷击式 DDoS。
太温和。 1 分钟内重试 3 次就放弃。客户的发布要 10 分钟；事件丢了。

走得通的模式：带 jitter 的截断指数退避，限定保留时长。

我们的时间表：

T+0s — 首次尝试
T+10s — 第一次重试（如首次失败）
T+30s
T+1m
T+5m
T+15m
T+1h
T+6h
T+24h — 最终尝试

24 小时内总共 9 次。每次重试有 ±25% 的 jitter。9 次失败后事件进 DLQ。

这能抓住大约 97% 可恢复的客户端点，并把对损坏端点的负载控制在 9 次 / 24 小时。

什么算"成功"？

我们把 2xx 范围内的任意 HTTP 状态码 视为成功。具体：

200 — 显式成功
201、202、204 — 同样视为成功
任何 3xx — 我们最多跟 2 跳重定向，再之后视为失败
4xx — 失败，重试（也许端点配置错了，但能修）
5xx — 失败，重试
连接错误 / 超时 — 失败，重试

为什么对 4xx 也重试？

传统说法是"4xx 是客户端的错，别重试"。现实是：401 可能意味着客户在轮换密钥并修复 bug；404 可能意味着代理配错；422 可能意味着 schema 校验有问题。把 4xx 当作终态，会因为本来几分钟就能修的瞬时错误惩罚客户。重试，但要打响亮的日志。

HMAC 签名

每一个 webhook 请求体必须签名。模式：

客户注册端点，我们生成一个密钥（32 字节随机，hex 编码）
每次投递，我们计算 HMAC-SHA256(secret, timestamp + "." + body)，作为 X-Kxp-Signature: t=<ts>,v1=<hex> 头发出
客户处理函数：
- 读出 timestamp 与 signature 头
- 验证 timestamp 在 ±5 分钟内（防重放）
- 重新计算 timestamp + "." + body 的 HMAC
- 用常时间比较

我们在文档里发布了主流语言的验证示例。

我们见过的两个反模式：

只签 body，不签 timestamp。 易被重放攻击。
把 secret 写进源码。 客户会 commit 进仓库。文档里要响亮地说明放在 env 或 vault。

接收方的幂等性

和我们支付 API 幂等那篇同样的理念，镜像应用：

我们对每个业务事件发布唯一 event_id（UUIDv4）
不管投递尝试多少次，重试时都用 同一个 event_id
接收方按 event_id 去重

如果你正在集成任何支付服务商的 webhook，处理函数骨架应是：

async function handleWebhook(req) {
  const sig = req.headers['x-kxp-signature'];
  const body = await req.text();

  if (!verifySig(sig, body, process.env.KXP_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(body);

  // Dedup on event_id
  const existing = await db.events.findOne({ event_id: event.id });
  if (existing) return res.status(200).send('Already processed');

  await db.events.insert({ event_id: event.id, status: 'processing' });

  try {
    await processEvent(event);
    await db.events.update(event.id, { status: 'done' });
    return res.status(200).send('OK');
  } catch (e) {
    await db.events.update(event.id, { status: 'failed', error: e.message });
    return res.status(500).send('Retry me');
  }
}

处理前的去重检查至关重要。少了它，慢处理函数在仍在运行时被重试，就会双倍处理。