Webhooks 详解:签名负载与重试机制
为什么 Webhooks 在生产环境中会出问题
你已经构建了一个 webhook 端点,在本地测试过,一切正常。然后生产环境来了:提供方发送了重复事件,你的端点超时,或者攻击者伪造了请求。突然之间,你的集成变得不可靠且不安全。
Webhooks 概念上很简单——由事件触发的 HTTP 回调——但生产级实现需要仔细处理安全性和可靠性。本指南涵盖两个关键方面:用于验证真实性的签名负载,以及处理失败的重试策略。
什么是 Webhooks?
Webhook 是用户定义的 HTTP 回调。当源系统中发生事件时(例如支付成功),它会向你提供的 URL 发送一个 HTTP POST 请求,其中包含有关事件的数据。这种推送模型比轮询更高效。
但 webhooks 也带来了挑战:
- 安全性:你如何知道请求来自合法的发送方?
- 可靠性:如果你的端点宕机或响应缓慢怎么办?
- 重复:网络可能导致重试;你可能会多次收到同一个事件。
让我们先解决安全性问题。
使用签名负载保护 Webhooks
签名负载使用共享密钥为请求体创建加密签名。发送方将此签名包含在标头中(例如 X-Signature)。你的端点重新计算签名并进行比较。如果匹配,则请求是真实的。
HMAC 签名的工作原理
大多数提供方使用 HMAC-SHA256。签名是使用共享密钥对原始请求体计算得出的。以下是流程:
- 提供方和消费者共享一个密钥。
- 提供方创建负载,计算 HMAC-SHA256(secret, payload),并将其放在标头中发送。
- 消费者接收请求,读取原始请求体,计算相同的 HMAC,并进行比较。
重要:使用接收到的原始请求体——解析并重新序列化 JSON 可能会改变字节并破坏签名。
实现签名验证
以下是使用 Express 的 Node.js 示例:
const crypto = require('crypto');
const express = require('express');
const app = express();
// Use raw body parser for webhook routes
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// Process the event
const event = JSON.parse(req.body);
// ... handle event
res.status(200).send('OK');
});
始终使用像 crypto.timingSafeEqual 这样的恒定时间比较来防止时序攻击。
其他安全考虑
- 时间戳验证:在签名负载中包含时间戳,并拒绝旧请求以防止重放攻击。
- HTTPS:Webhook 端点始终使用 HTTPS。
- 密钥轮换:支持多个活跃密钥,以便在不中断服务的情况下进行轮换。
实现可靠的重试
即使端点安全,网络问题或临时故障也可能导致 webhook 传递失败。健壮的重试机制确保事件不会丢失。
发送方重试策略
如果你正在构建 webhook 发送方,请实现带抖动的指数退避。例如:
- 重试 1:1 分钟后
- 重试 2:5 分钟后
- 重试 3:30 分钟后
- 重试 4:2 小时后
- 重试 5:24 小时后
添加随机抖动以避免惊群问题。在达到最大尝试次数后停止并发出警报。
接收方最佳实践
作为 webhook 消费者,你无法控制发送方的重试策略,但你可以使端点更具弹性:
- 快速响应:在处理繁重工作之前,用 2xx 状态确认接收。使用队列。
- 幂等性:优雅地处理重复事件。使用事件 ID 进行去重。
- 监控失败:记录失败并设置警报。
使用幂等性处理重复
Webhook 提供方通常会在超时时重试,因此你可能会多次收到同一个事件。使处理具有幂等性:
- 将已处理的事件 ID 存储在具有唯一约束的数据库中。
- 在处理之前,检查 ID 是否已存在;如果存在,则返回 200 OK 而不重新处理。
- 对于状态更改操作,使用幂等键。
使用数据库唯一索引的示例:
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // unique violation
return; // already processed
}
throw err;
}
// process event
}
比较:Webhook 安全方法
| 方法 | 优点 | 缺点 |
|---|---|---|
| HMAC 签名 | 强完整性,广泛支持 | 需要密钥管理 |
| 基本认证 | 简单 | 安全性较低,凭据在标头中 |
| IP 允许列表 | 易于实现 | IP 可能变化,不够健壮 |
HMAC 签名是 webhook 安全的事实标准。
本地测试 Webhooks
像 ngrok 或 localtunnel 这样的工具可以将你的本地服务器暴露到互联网进行测试。始终使用模拟故障测试签名验证和重试逻辑。
在检查来自 webhooks 的 JSON 负载时,格式化它们有助于调试。尝试我们的 JSON Formatter 来美化打印和验证 webhook 负载。
常见问题
如何验证 webhook 签名?
使用共享密钥对原始请求体计算 HMAC,然后使用恒定时间比较函数将其与签名标头进行比较。
如果我的 webhook 端点宕机了该怎么办?
大多数提供方会使用指数退避进行重试。确保你的端点快速返回 2xx 并异步处理,以最小化停机影响。
我可以不使用签名而使用 webhooks 吗?
这有风险。没有签名,攻击者可以伪造请求。始终使用签名负载,或者至少通过 HTTPS 使用基本认证。
结论
Webhooks 功能强大,但需要注意安全性和可靠性。实现 HMAC 签名验证以确保真实性,并设计系统以优雅地处理重试和重复。通过这些实践,你的 webhook 集成将健壮且适用于生产环境。