Webhooks 详解:签名负载与重试机制实现可靠集成
你刚刚构建了一个端点来接收支付提供商的 Webhook。第一次测试正常,但在生产环境中你发现事件丢失、重复扣款,而且无法判断请求是否真实。Webhook 概念简单但实现起来却容易出错。本指南将解释如何使用签名负载保护 Webhook,并实现健壮的重试逻辑,使你的集成不会悄无声息地失败。
什么是 Webhook 及其重要性
Webhook 是由事件触发的用户定义 HTTP 回调。你的应用程序不必轮询 API 来获取变更,而是由服务在事件发生时将数据推送到你的端点。这使得集成高效且近乎实时。
常见用例包括支付通知(如 Stripe)、CI/CD 触发器(如 GitHub)和消息平台(如 Slack)。但采用这种推送模式,你无法控制请求到达的时间。这就是为什么你需要显式处理安全性和可靠性。
安全问题:未签名的 Webhook 是危险的
未签名的 Webhook 只是向公共 URL 发送的 HTTP POST 请求。任何人都可以发送看起来像是来自你的支付提供商的请求。如果没有验证,攻击者可以伪造事件,导致欺诈订单、数据泄露或未经授权的操作。
解决方案是对负载进行签名。发送方使用共享密钥对请求体计算加密签名,并将其包含在头部中。你的端点重新计算签名并进行比较。如果匹配,你就知道请求是真实的且未被篡改。
如何使用 HMAC 对 Webhook 负载进行签名
HMAC(基于哈希的消息认证码)是 Webhook 签名的标准。它使用密钥和哈希函数(如 SHA-256)生成对负载和密钥唯一的签名。
以下是发送方在 Python 中签名负载的示例:
import hmac
import hashlib
import json
secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature:
在接收端,你必须在处理负载之前验证签名:
import hmac
import hashlib
def verify_signature(payload, received_signature, secret):
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)
重要:始终使用恒定时间比较函数(如 hmac.compare_digest)以防止时序攻击。此外,务必针对原始请求体验证签名,而不是解析后的版本,因为 JSON 序列化可能不同。
签名负载的最佳实践
- 使用强密钥:生成至少 32 字节的随机密钥并安全存储(例如,环境变量或密钥管理器)。
- 包含时间戳:在签名负载中添加时间戳,并拒绝超过几分钟的请求以防止重放攻击。
- 使用 HTTPS:始终通过 TLS 传输 Webhook,以保护传输中的负载和签名。
- 定期轮换密钥:在轮换期间支持多个活动密钥以避免停机。
处理失败:重试与幂等性
Webhook 可能会失败:你的服务器可能宕机、网络可能中断,或者你的端点可能返回错误。可靠的发送方会重试投递,但你必须设计接收方来处理重复和乱序事件。
重试策略
大多数 Webhook 提供商使用带抖动的指数退避。例如,在 1 分钟后重试,然后 5 分钟,然后 30 分钟,直到达到最大尝试次数。这给你的系统时间恢复,而不会使其过载。
如果你在构建发送方,请实现一个带有计划重试的队列。存储负载和尝试次数,并使用工作进程处理重试。
幂等性:安全重试的关键
由于重试可能导致重复投递,你的端点必须是幂等的。这意味着多次处理同一事件的效果应与处理一次相同。
常见方法:
- 使用唯一事件 ID:在负载中包含 ID,并将已处理的 ID 存储在数据库中。忽略你已见过 ID 的事件。
- 设计幂等操作:例如,使用 upsert 而不是 insert,或者在创建资源之前检查其是否已存在。
以下是一个简单的 Python 幂等性检查:
def process_event(event_id, payload):
if db.exists('processed_events', event_id):
return # already processed
# process payload
db.insert('processed_events', event_id)
确保检查和数据处理在单个事务中发生,以避免竞态条件。
比较:轮询 vs. Webhook
| 方面 | 轮询 | Webhook |
|---|---|---|
| 延迟 | 取决于间隔(例如 5 分钟) | 近乎实时 |
| 服务器负载 | 即使没有变化也持续请求 | 仅在事件发生时请求 |
| 复杂性 | 实现简单 | 需要签名、重试、幂等性 |
| 可靠性 | 你控制重试 | 取决于发送方的重试策略 |
分步指南:实现安全的 Webhook 接收器
- 设置一个 HTTPS 端点,接受 POST 请求并读取原始请求体。
- 提取签名头部(例如
X-Signature)以及时间戳头部(如果存在)。 - 使用 HMAC 和你的密钥验证签名。如果无效则拒绝。
- 检查时间戳以防止重放攻击(例如,拒绝超过 5 分钟的请求)。
- 解析负载并提取事件 ID。
- 检查幂等性,在数据库中查找事件 ID。
- 在事务中处理事件,同时记录事件 ID。
- 快速返回 2xx 状态以确认收到。如果处理需要时间,将任务加入队列并返回 202 Accepted。
测试你的 Webhook 实现
使用 ngrok 等工具暴露你的本地服务器并模拟 Webhook。为签名验证、幂等性和重试逻辑编写单元测试。例如,测试重复事件 ID 被忽略,以及无效签名返回 401。
调试时,记录收到的负载和签名(但绝不记录密钥)。如果你处理 JSON 负载,JSON 格式化工具可以帮助你快速检查和验证结构。
常见问题
什么是签名的 Webhook 负载?
签名负载包含使用共享密钥对请求体计算的加密签名(通常是 HMAC)。接收方验证签名以确保请求真实且未被篡改。
Webhook 应该重试多少次?
没有统一标准,但常见做法是使用指数退避进行 3–5 次重试。之后,事件通常被标记为失败,可能需要手动干预或进入死信队列。
我可以不使用 HTTPS 使用 Webhook 吗?
绝不应通过纯 HTTP 使用 Webhook。没有 TLS,攻击者可以拦截负载和签名,并重放或修改请求。始终使用 HTTPS。
准备好检查和格式化 Webhook 负载了吗?试试我们免费的 JSON 格式化工具,立即验证和美化 JSON 数据。