Webhooks 详解:签名负载与可靠重试
你上线了一个支付集成,在预发布环境中一切正常。但在生产环境中,客户付款后,你的端点超时了两秒钟,订单始终没有激活。与此同时,支付提供商对同一事件重试了三次,而你的应用为那个确实成功的事件创建了三个重复订单。Webhook 看起来很简单——只是一个 HTTP POST——但难点在于信任和投递保证。
本文涵盖 Webhook 集成中最常出问题的两件事:验证请求确实来自发送方,以及处理重试而不产生重复的副作用。
Webhook 到底是什么
Webhook 是一种反向 API 调用。你的服务器不需要每分钟轮询提供商询问“有什么新情况吗?”,而是由提供商在事件发生时向你注册的 URL 推送一个 HTTP 请求。负载通常是 JSON,事件类型要么在请求体中,要么在请求头中。
POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592
{
"id": "evt_8f2c1a",
"type": "payment.succeeded",
"created": 1735689600,
"data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}在发送方有两个重要的设计决策,在评估任何提供商时你都应该检查这两点:它是否对负载进行签名?失败时是否会重试?
为什么未签名的 Webhook 很危险
你的 Webhook URL 是公开的。任何知道它的人都可以 POST 一个伪造的 payment.succeeded 事件,将未支付的订单标记为已支付。IP 允许列表有一点帮助,但提供商会更换 IP、运行在 CDN 后面,而且你可能拿不到稳定的列表。
稳健的解决方案是使用只有你和提供商知道的共享密钥,对原始请求体进行 HMAC 签名。提供商计算签名并放在请求头中发送;你重新计算并比较。
正确验证签名
有三个细节很容易出错:
- 使用原始请求体。只在验证之后才解析 JSON。重新序列化已解析的对象会改变空白和键的顺序,因此签名将永远无法匹配。
- 使用恒定时间比较。简单的字符串比较会泄露时序信息。使用时序安全的函数。
- 将时间戳包含在签名字符串中。对
timestamp.body签名可以让你拒绝旧请求并阻止重放攻击。
// Node.js / Express 示例
const crypto = require('crypto');
function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
header.split(',').map(p => p.split('='))
);
const timestamp = Number(parts.t);
if (!timestamp) return false;
// 拒绝过期请求(重放保护)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body.toString());
// ... 处理事件
res.status(200).send('ok');
});注意 express.raw() 中间件。如果你在此路由之前挂载了 express.json(),请求体已经被解析,签名检查会静默失败——这是一个非常常见的 bug。
设计不丢失事件的重试机制
Webhook 投递是至少一次,而非恰好一次。网络会故障,你的部署会重启容器,提供商不知道你的 200 响应是否真实。因此提供商会使用指数退避进行重试,通常持续数小时或数天。
快速响应,稍后处理
你的端点应该做最少的工作:验证、持久化原始事件、返回 2xx。繁重的工作——发送邮件、调用其他 API、生成发票——应该在后台任务中完成。如果处理时间超过提供商的超时时间,请求会被视为失败并重试,即使你已经完成了工作。
- 验证签名和时间戳。
- 将事件插入到对事件 ID 有唯一约束的表中。
- 立即返回
200。 - 异步处理已存储的事件,并将其标记为完成。
幂等性:重复问题的真正解决方案
由于重试会发生,你的处理程序必须能够安全地运行两次。事件 ID 是天然的幂等键。
INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;如果插入影响零行,说明你以前见过此事件——确认并继续。对于业务逻辑,应用同样的思路:在激活支付时使用订单 ID 作为唯一键,这样第二个事件就不会创建第二次激活。
有意识地选择状态码
| 状态码 | 提供商行为 | 何时使用 |
|---|---|---|
| 200 / 204 | 标记为已投递 | 事件已接受(即使已处理过) |
| 400 | 通常不重试 | 永远无法处理的格式错误负载 |
| 401 | 通常不重试 | 签名不匹配——检查你的密钥 |
| 429 | 退避重试 | 你正在进行速率限制 |
| 500 / 503 | 退避重试 | 临时故障、数据库宕机、部署进行中 |
对于无法存储的事件返回 200 是最糟糕的选择:提供商会停止重试,事件将永远丢失。返回 5xx,让重试发挥作用。
生产环境实用清单
- 仅使用 HTTPS;绝不接受明文 HTTP 的 Webhook。
- 将签名密钥存储在密钥管理器中,并支持轮换——许多提供商允许两个活动密钥。
- 为每个请求记录事件 ID、类型、签名结果和处理结果。
- 设置容忍窗口(通常五分钟)以阻止重放。
- 在数据库层面使处理程序幂等,而不仅仅是在应用代码中。
- 当失败率或处理延迟超过阈值时发出警报。
- 为支持人员提供手动重放端点。
在本地测试 Webhook
你无法轻易在 localhost 上接收公开的 POST 请求。选项包括:暴露开发端口的隧道工具、提供商的 CLI(如果有的话),或者一个小脚本,向你的处理程序发送签名负载,以便你测试验证路径。
最有价值的测试是重复事件:发送同一个事件两次,确认你的系统最终处于相同状态。然后发送一个带有旧时间戳的事件,确认它被拒绝。再篡改请求体的一个字节,确认签名检查失败。
调试负载
Webhook 请求体是 JSON,格式错误或深度嵌套的负载在日志中很难阅读。格式化工具可以帮助你在编写解析代码之前快速检查结构。JSON 格式化工具在浏览器中运行,因此你可以粘贴捕获的负载,而无需将客户数据发送到服务器。
常见问题
Webhook 和 API 有什么区别?
API 是基于拉取的:你的代码在需要数据时调用提供商。Webhook 是基于推送的:提供商在事件发生时调用你的端点。大多数集成同时使用两者——Webhook 用于事件通知,API 用于获取完整详情或执行操作。
为什么我的 HMAC 签名永远不匹配?
常见原因是对重新序列化的请求体而不是原始字节进行签名。空白、键顺序和 Unicode 转义都会改变哈希值。在任何 JSON 中间件之前读取原始请求体,并确认密钥和哈希算法与提供商的文档一致。
Webhook 重试有保证吗?
没有。提供商通常会在有限的时间窗口内使用指数退避进行重试,然后放弃。将 Webhook 视为快速通知渠道,而不是事实来源:定期与提供商的 API 进行对账,以便最终纠正遗漏的事件。
如果你今天正在构建或调试 Webhook 接收器,请从锁定签名验证和幂等存储开始——这两项更改可以消除现实世界中大多数 Webhook 事故。