Webhook 详解:签名载荷与重试机制
你刚刚集成了支付提供商或 CI/CD 服务,现在需要接收实时事件。Webhook 是系统间推送数据的标准方式,但许多实现因安全漏洞或不可靠的交付而在生产环境中失败。本指南解释如何使用签名载荷保护 Webhook 安全,并实现健壮的重试机制。
什么是 Webhook 及其重要性
Webhook 是一种 HTTP 回调:当源系统中发生事件(例如新订单)时,它会向您提供的 URL 发送 HTTP POST 请求。与轮询不同,Webhook 高效且近乎实时。然而,由于基于 HTTP,您必须显式处理安全性和可靠性。
常见用例包括支付通知、CI/CD 流水线触发、聊天通知以及在 SaaS 应用程序之间同步数据。
使用签名载荷保护 Webhook 安全
Webhook 是公开可访问的端点,因此攻击者可以发送伪造请求。为防止这种情况,提供商会使用密钥对每个载荷进行签名。接收方验证签名以确保真实性和完整性。
HMAC 签名的工作原理
最常见的方法是 HMAC-SHA256。提供商使用共享密钥计算请求体的哈希,并将其包含在头部(例如 X-Signature)中。接收方重新计算哈希并进行比较。
// Node.js 示例:生成签名
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// 在头部中发送签名:X-Signature: sha256=...
在接收方验证签名
始终使用恒定时间比较以防止时序攻击。在 Node.js 中,使用 crypto.timingSafeEqual。
// Express.js 中间件示例
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // 需要原始请求体
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
重要: 使用原始请求体进行验证,而不是解析后的 JSON,以避免差异。
附加安全措施
- 时间戳验证: 在签名中包含时间戳,并拒绝超过几分钟的请求以防止重放攻击。
- 仅使用 HTTPS: 始终使用 HTTPS 端点以保护传输中的数据。
- IP 允许列表: 如果提供商发布 IP 范围,请将传入请求限制为这些 IP。
实现可靠的重试
Webhook 可能因网络问题、服务器停机或错误而失败。提供商通常使用指数退避重试失败的交付。作为接收方,您必须具有幂等性并处理重复事件。
为幂等性设计
每个 Webhook 事件应具有唯一 ID。存储已处理的 ID 以忽略重复项。使用具有唯一约束的数据库或像 Redis 这样的缓存。
// 幂等处理的伪代码
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24 小时 TTL
重试策略
提供商通常以递增的延迟重试(例如 1 秒、5 秒、30 秒、5 分钟、1 小时)。确保您的端点快速响应(5 秒内)以避免超时。如果处理时间较长,请确认收到并异步处理。
以下是常见重试模式的比较:
| 模式 | 优点 | 缺点 |
|---|---|---|
| 固定间隔 | 简单 | 可能对恢复中的服务器造成压力 |
| 指数退避 | 在中断期间减少负载 | 瞬时错误导致交付延迟 |
| 带抖动的指数退避 | 防止惊群效应 | 稍微复杂 |
监控和死信队列
记录所有 Webhook 尝试和失败。在达到最大重试次数后,将事件移至死信队列 (DLQ) 以供手动检查。对高失败率发出警报。
整合所有内容:分步实现
- 设置一个 HTTPS 端点,接受 POST 请求并读取原始请求体。
- 验证签名,使用共享密钥和恒定时间比较。
- 检查时间戳 以防止重放攻击(如果提供)。
- 确保幂等性,通过检查事件 ID 与缓存或数据库。
- 异步处理事件 如果可能需要时间;立即返回 200 OK。
- 在发送方实现重试逻辑,使用指数退避和抖动。
- 监控和警报 失败情况,并使用 DLQ 处理持续错误。
常见问题
什么是签名的 Webhook 载荷?
签名载荷包含加密签名(通常是 HMAC),允许接收方验证请求来自可信来源且未被篡改。
如何处理重复的 Webhook 事件?
使用载荷中提供的唯一事件 ID 跟踪已处理的事件。将 ID 存储在数据库或缓存中,并设置 TTL 以忽略重复项。
我的 Webhook 端点应返回什么?
快速返回 2xx 状态码(例如 200 OK)以确认收到。如果处理失败,返回 5xx 以触发重试,但仅针对瞬时错误。
在测试 Webhook 载荷时,您可能需要检查 JSON 结构。使用 JSON Formatter 验证和美化 Webhook 载荷,以便更轻松地调试。