Webhooks 详解:签名载荷与可靠重试

Backend2026-11-17TryQuickToolBox

你刚刚集成了一项第三方服务,它会向你的端点发送 webhook。测试中一切正常,但在生产环境中,你发现事件丢失、重复投递,甚至出现伪造请求。Webhook 概念简单,但要正确实现却并不容易。本文讲解如何通过签名载荷保护 webhook 安全,并实现可靠的重试逻辑,让你的集成健壮且值得信赖。

什么是 Webhook,为何重要

Webhook 是由事件触发的用户自定义 HTTP 回调。你无需轮询 API 来获取变更,而是注册一个 URL,当有事件发生时,服务会向该 URL 发送包含事件数据的 POST 请求。这种推送模型降低了延迟和服务器负载,非常适合支付通知、CI/CD 触发和聊天消息等实时集成场景。

然而,webhook 也带来了挑战:验证真实性、处理失败以及确保恰好一次处理。让我们逐一解决这些问题。

使用签名载荷保护 Webhook

如果不做验证,任何人都可以向你的 webhook 端点发送伪造请求。签名载荷通过在请求头中包含一个使用共享密钥生成的加密签名来解决这一问题。你验证签名,即可确认请求来自预期的发送方,且未被篡改。

HMAC 签名的工作原理

大多数服务使用 HMAC(基于哈希的消息认证码)配合 SHA-256。发送方使用密钥对请求体(有时还包括时间戳)计算哈希,并将其放入类似 X-Signature 的请求头中。你在自己这一端重新计算哈希并进行比较。

以下是 Node.js 中典型的验证流程:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

务必使用恒定时间比较以防止时序攻击。此外,在签名数据中包含时间戳,并拒绝超过几分钟的请求,以防止重放攻击。

签名验证的最佳实践

实现可靠的重试

网络会失败,服务器会重启,端点会超时。健壮的 webhook 系统必须对失败的投递进行重试。但重试可能导致重复,因此你需要幂等性。

重试策略

大多数提供方使用带抖动的指数退避。例如,在 1 分钟后重试,然后 5 分钟,再然后 30 分钟,直到达到最大尝试次数(例如 5 次)。在载荷中包含唯一的事件 ID,以便接收方去重。

在接收端,快速返回 2xx 状态码以确认收到,然后异步处理。如果处理失败,你不能指望发送方无限重试——请实现自己的死信队列或告警机制。

幂等键

为处理重复投递,请使用幂等键(通常是事件 ID),并在合理的时间段内存储已处理的 ID。在处理之前,检查该 ID 是否已出现过;如果出现过,则直接返回成功而不重复处理。

// 示例:Express 中的幂等性检查
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // 异步处理事件
  res.status(200).send('OK');
});

对比:轮询 vs Webhook

方面轮询Webhook
延迟高(基于间隔)低(近实时)
服务器负载高(频繁请求)低(事件驱动)
复杂度实现简单需要签名验证和重试
可靠性取决于轮询频率取决于重试机制

分步指南:构建安全的 Webhook 接收端

  1. 设置端点,通过 HTTPS 接受 POST 请求。
  2. 验证签名,使用共享密钥并以 401 拒绝无效请求。
  3. 检查时间戳以防止重放攻击。
  4. 立即响应,在基本验证后返回 200 OK,然后异步处理。
  5. 实现幂等性,使用事件 ID 避免重复处理。
  6. 记录并监控失败和重试情况。

常见问题

什么是签名的 webhook 载荷?

签名载荷包含一个加密签名(通常是 HMAC),使接收方能够使用共享密钥验证请求的真实性和完整性。

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

常见做法是使用指数退避重试 3–5 次。之后,将事件移至死信队列以便人工检查。

可以在不使用 HTTPS 的情况下使用 webhook 吗?

不可以,HTTPS 对于保护载荷和签名免受窃听和篡改至关重要。请始终使用 TLS。

准备好测试你的 webhook 载荷了吗?使用我们的 JSON 格式化工具快速美化并验证 JSON 载荷。