Webhooks 详解:签名负载与重试策略
你已经构建了一个 API,通过发送 webhook 来通知外部服务有关事件的发生。但是,当接收端点宕机时会发生什么?或者当恶意行为者试图伪造 webhook 请求时呢?如果没有适当的保护措施,你的 webhook 可能成为数据不一致和安全漏洞的来源。本文解释了如何实现签名负载和重试机制,以使你的 webhook 可靠且安全。
什么是 Webhook,为什么需要安全?
Webhook 是由特定事件触发的用户定义的 HTTP 回调。它们实现了系统之间的实时通信,例如在下单时通知支付服务。然而,由于 webhook 是公开可访问的端点,它们容易受到欺骗和重放攻击。此外,网络问题或接收方停机可能导致事件丢失。因此,必须解决两个关键方面:真实性(通过签名负载)和可靠性(通过重试)。
签名负载:确保真实性和完整性
签名负载允许接收方验证 webhook 来源于可信来源,并且数据未被篡改。这通常通过使用共享密钥的 HMAC(基于哈希的消息认证码)来实现。
HMAC 签名的工作原理
发送方和接收方共享一个密钥。对于每个 webhook 请求,发送方使用密钥和请求负载(通常包括时间戳以防止重放攻击)计算 HMAC 签名。签名在头部中发送,例如 X-Signature。接收方重新计算签名并与收到的签名进行比较。如果匹配,则请求是真实的。
以下是使用 HMAC-SHA256 的 Python 示例:
import hmac
import hashlib
import time
secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
# Send headers: X-Signature: signature, X-Timestamp: timestamp
在接收方,验证签名并检查时间戳以确保请求是最近的(例如,在 5 分钟内)。这可以防止重放攻击。
签名负载的最佳实践
- 使用强密钥:生成一个随机、高熵的密钥并安全存储。
- 包含时间戳:拒绝时间戳超出可接受窗口的请求。
- 使用恒定时间比较:通过使用
hmac.compare_digest等函数防止时序攻击。 - 定期轮换密钥:在轮换期间允许使用多个活动密钥。
重试机制:确保可靠交付
即使有签名负载,网络故障或接收方错误也可能导致 webhook 交付失败。稳健的重试策略确保事件最终被交付,而不会压垮接收方。
设计重试策略
一种常见的方法是带抖动的指数退避。例如,在 1 分钟后重试,然后 5 分钟,然后 30 分钟,直到最大尝试次数(例如 5 次)。在负载中包含唯一的事件 ID,以便接收方可以去重。
重试计划示例:
| 尝试 | 延迟 |
|---|---|
| 1 | 立即 |
| 2 | 1 分钟 |
| 3 | 5 分钟 |
| 4 | 30 分钟 |
| 5 | 2 小时 |
在耗尽重试次数后,将事件移动到死信队列以供手动检查。
幂等性:处理重复交付
由于重试可能导致重复交付,接收方必须是幂等的。在负载中包含事件 ID,并让接收方存储已处理的 ID 以忽略重复项。或者,将操作设计为自然幂等(例如,使用 PUT 而不是 POST)。
实现 Webhook:分步指南
- 定义事件和负载结构:记录系统发出的事件以及每个事件的 JSON 模式。
- 生成密钥:为每个 webhook 端点创建唯一的密钥并安全共享。
- 对每个请求签名:基于负载和时间戳计算 HMAC,并包含在头部中。
- 实现带退避的重试:使用队列系统来安排重试。
- 提供验证签名的方法:为接收方记录验证过程。
- 监控和日志:跟踪交付尝试和失败以进行调试。
常见陷阱及如何避免
- 忽略 TLS:始终使用 HTTPS 以保护传输中的负载。
- 不验证时间戳:允许重放攻击。
- 无限重试:可能导致资源耗尽;设置最大值。
- 假设立即交付:为异步处理而设计。
常见问题
什么是签名 webhook 负载?
签名 webhook 负载包含一个加密签名(例如 HMAC),允许接收方验证发送方的真实性和数据完整性。
我应该重试失败的 webhook 多少次?
通常使用指数退避进行 3 到 5 次重试。具体次数取决于你的 SLA 和事件的关键性。
我可以使用 JWT 而不是 HMAC 进行 webhook 签名吗?
是的,可以使用 JWT,但 HMAC 更简单且更常用于 webhook 签名。JWT 增加了开销,更适合用于认证令牌。
准备好测试你的 webhook 负载了吗?使用我们的 JSON 格式化工具 在发送前验证和美化你的 JSON 负载。