Webhooks 详解:签名负载与重试策略

Backend2026-11-12TryQuickToolBox

你已经构建了一个 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 分钟内)。这可以防止重放攻击。

签名负载的最佳实践

重试机制:确保可靠交付

即使有签名负载,网络故障或接收方错误也可能导致 webhook 交付失败。稳健的重试策略确保事件最终被交付,而不会压垮接收方。

设计重试策略

一种常见的方法是带抖动的指数退避。例如,在 1 分钟后重试,然后 5 分钟,然后 30 分钟,直到最大尝试次数(例如 5 次)。在负载中包含唯一的事件 ID,以便接收方可以去重。

重试计划示例:

尝试延迟
1立即
21 分钟
35 分钟
430 分钟
52 小时

在耗尽重试次数后,将事件移动到死信队列以供手动检查。

幂等性:处理重复交付

由于重试可能导致重复交付,接收方必须是幂等的。在负载中包含事件 ID,并让接收方存储已处理的 ID 以忽略重复项。或者,将操作设计为自然幂等(例如,使用 PUT 而不是 POST)。

实现 Webhook:分步指南

  1. 定义事件和负载结构:记录系统发出的事件以及每个事件的 JSON 模式。
  2. 生成密钥:为每个 webhook 端点创建唯一的密钥并安全共享。
  3. 对每个请求签名:基于负载和时间戳计算 HMAC,并包含在头部中。
  4. 实现带退避的重试:使用队列系统来安排重试。
  5. 提供验证签名的方法:为接收方记录验证过程。
  6. 监控和日志:跟踪交付尝试和失败以进行调试。

常见陷阱及如何避免

常见问题

什么是签名 webhook 负载?

签名 webhook 负载包含一个加密签名(例如 HMAC),允许接收方验证发送方的真实性和数据完整性。

我应该重试失败的 webhook 多少次?

通常使用指数退避进行 3 到 5 次重试。具体次数取决于你的 SLA 和事件的关键性。

我可以使用 JWT 而不是 HMAC 进行 webhook 签名吗?

是的,可以使用 JWT,但 HMAC 更简单且更常用于 webhook 签名。JWT 增加了开销,更适合用于认证令牌。

准备好测试你的 webhook 负载了吗?使用我们的 JSON 格式化工具 在发送前验证和美化你的 JSON 负载。