Webhooks 详解：签名载荷与重试策略

Backend2026-10-21TryQuickToolBox

您已经构建了一个 API，向用户的端点发送 webhook。但随后您面临经典问题：如何确保载荷未被篡改？当端点宕机时会发生什么？如何防止重复处理？在本文中，我们将通过签名载荷和稳健的重试策略正面解决这些挑战。

为什么 Webhook 需要签名

Webhook 是通知其他系统事件的 HTTP 回调。由于它们通过公共互联网发送，因此容易受到拦截和欺骗。没有签名，恶意行为者可以向您的用户发送虚假 webhook，触发意外操作。使用共享密钥对载荷进行签名可确保真实性和完整性。

签名载荷的工作原理

最常见的方法是使用 HMAC（基于哈希的消息认证码）和 SHA-256。发送方和接收方共享一个密钥。发送方对载荷（有时还包括时间戳）计算签名，并将其包含在头部中。接收方重新计算签名并与收到的签名进行比较。

分步指南：对载荷进行签名

创建载荷：将事件数据序列化为 JSON。确保格式一致（例如，没有多余的空格），因为签名是基于精确字节计算的。
添加时间戳：在载荷或头部中包含 Unix 时间戳，以防止重放攻击。接收方可以拒绝超过几分钟的请求。
计算 HMAC：使用您的密钥生成载荷字符串（或时间戳 + 载荷）的 HMAC-SHA256。
附加签名：在类似 X-Signature 的头部中发送它。

以下是 Python 示例：

import hmac
import hashlib
import json
import time

secret = b'your_shared_secret'
payload = {"event": "user.created", "data": {"id": 123}}
body = json.dumps(payload, separators=(',', ':'))
timestamp = str(int(time.time()))
signed_content = timestamp + '.' + body
signature = hmac.new(secret, signed_content.encode(), hashlib.sha256).hexdigest()

# Send headers: X-Signature: signature, X-Timestamp: timestamp

验证签名

在接收端，您必须：

从头部提取时间戳和签名。
如果时间戳太旧（例如超过 5 分钟），则拒绝，以防止重放攻击。
使用相同的方法重新计算签名。
使用恒定时间函数进行比较，以避免时序攻击。

Node.js 中的验证示例：

const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-signature'];
  const timestamp = req.headers['x-timestamp'];
  if (!signature || !timestamp) return false;
  if (Date.now() / 1000 - timestamp > 300) return false; // 5 min
  const body = JSON.stringify(req.body);
  const signed = timestamp + '.' + body;
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

设计重试策略

即使有签名，webhook 也可能因网络问题、服务器错误或超时而失败。稳健的重试策略可确保送达，同时不会压垮接收方。

关键考虑因素

幂等性：接收方应优雅地处理重复事件。使用幂等键（例如事件 ID）进行去重。
指数退避：在逐渐增加的延迟后重试（例如 1 秒、5 秒、30 秒、5 分钟、30 分钟），给接收方恢复的时间。
最大重试次数：设置限制（例如 5 次尝试），然后将 webhook 标记为失败，或许提醒用户。
超时：为每次尝试设置合理的超时（例如 10 秒）。

实现重试

大多数 webhook 发送方使用队列系统（例如 Redis、RabbitMQ 或数据库）来安排重试。以下是一个简化的流程：

事件触发时，将带有载荷和目标 URL 的 webhook 任务入队。
工作进程取出任务并尝试送达。
如果响应状态为 2xx，则标记为成功。
如果不是，则使用指数退避安排重试，直到达到最大尝试次数。
达到最大尝试次数后，标记为失败并通知。

重试计划示例：

尝试	延迟
1	立即
2	1 分钟
3	5 分钟
4	30 分钟
5	2 小时

Webhook 安全最佳实践

使用 HTTPS：始终通过 TLS 传递 webhook，以防止窃听。
轮换密钥：定期轮换共享密钥，并在轮换期间支持多个活动密钥。
验证 URL：确保 webhook URL 是 HTTPS，并且不指向内部 IP（以防止 SSRF）。
记录和监控：保留送达尝试和失败的日志，用于调试和审计。

常见问题

什么是签名的 webhook 载荷？

签名载荷包含一个加密签名（通常是 HMAC），允许接收方验证发送方的真实性以及载荷未被篡改。

失败的 webhook 应该重试多少次？

没有一刀切的答案，但常见的方法是 3–5 次重试，采用指数退避。考虑事件的关键性和接收方的容量。

我可以使用 JWT 进行 webhook 签名吗？

是的，可以使用 JWT，但更复杂。HMAC 更简单，对大多数用例来说足够。如果您需要在签名本身中包含声明或过期时间，JWT 很有用。