Webhook 详解：签名负载与重试逻辑

你已经构建了一个 API，现在需要在事件发生时通知其他服务。你决定实现 Webhook：将数据推送到订阅者 URL 的 HTTP 回调。但很快你面临两个关键问题：如何确保负载未被篡改？当接收服务器宕机或返回错误时会发生什么？如果没有适当的保护措施，Webhook 可能成为安全漏洞和可靠性噩梦。

在本指南中，我们将介绍使用签名负载保护 Webhook 安全以及实现健壮重试逻辑的基本要点。你将学习如何生成和验证 HMAC 签名、设计幂等处理器，并构建一个能优雅处理失败的重试机制。到最后，你将拥有一个生产就绪的 Webhook 方案。

为什么 Webhook 需要安全性和可靠性

Webhook 本质上是事件触发的服务器到服务器 HTTP 请求。与客户端发起的 API 调用不同，Webhook 是从你的服务器推送到订阅者端点的。这种推送模型引入了两个主要挑战：

• 安全性： 负载通过互联网传输，可能被拦截或欺骗。订阅者必须验证请求确实来自你的服务。
• 可靠性： 订阅者的服务器可能暂时不可用、响应缓慢或返回错误。你需要一种策略来重试失败的传递，同时避免重复处理。

忽视这些挑战可能导致数据泄露、事件丢失或系统间状态不一致。让我们逐一解决。

使用签名负载保护 Webhook 安全

签名负载使用加密哈希来证明请求的完整性和真实性。最常见的方法是使用共享密钥的 HMAC（基于哈希的消息认证码）。工作原理如下：

1. 共享密钥： 发送方（你的服务）和接收方（订阅者）共享一个密钥。该密钥在订阅者注册 Webhook 端点时生成。
2. 签名生成： 对于每个 Webhook 请求，发送方使用密钥计算请求体（有时还包括时间戳等头部）的 HMAC。签名通过头部发送，例如 X-Signature。
3. 签名验证： 接收方使用相同的密钥重新计算 HMAC，并与收到的签名进行比较。如果匹配，则负载是真实且未被修改的。

让我们看一个 Node.js 中生成和验证签名的代码示例。

const crypto = require('crypto');

// 发送方：生成签名
function generateSignature(payload, secret) {
  return crypto.createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
}

// 接收方：验证签名
function verifySignature(payload, secret, receivedSignature) {
  const expectedSignature = generateSignature(payload, secret);
  // 使用 timingSafeEqual 防止时序攻击
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(receivedSignature, 'hex')
  );
}

重要： 始终使用恒定时间比较函数（如 timingSafeEqual）以避免时序攻击。此外，在签名数据中包含时间戳以防止重放攻击。例如，签名 timestamp + '.' + payload 并拒绝超过几分钟的请求。

签名负载的最佳实践

• 使用 HMAC-SHA256 或更强算法。
• 在签名中包含时间戳并强制执行最大时效（例如 5 分钟）。
• 绝不在请求中传输密钥；它仅用于签名。
• 定期轮换密钥，并在轮换期间支持多个活动密钥。

实现可靠传递的重试逻辑

即使有了安全措施，Webhook 仍可能因网络问题、服务器错误或超时而失败。健壮的重试机制确保事件最终被传递。以下是分步方法：

1. 设置超时： 为 Webhook 请求定义合理的超时时间（例如 10 秒）。如果订阅者未及时响应，则视为失败。
2. 分类响应： 将 2xx 状态码视为成功。对于 4xx 错误（429 除外），重试通常无意义，因为请求无效。对于 5xx 错误和超时，使用指数退避进行重试。
3. 带抖动的指数退避： 以递增间隔安排重试（例如 1 秒、5 秒、30 秒、5 分钟、30 分钟），并添加随机抖动以避免惊群问题。
4. 限制重试次数： 设置最大尝试次数（例如 5 次），然后将传递标记为失败。可选地，通过电子邮件或仪表板通知订阅者。
5. 幂等性： 由于重试可能导致重复传递，在负载和头部中包含唯一事件 ID。订阅者应使用此 ID 去重处理。

以下是使用 requests 和 time 的 Python 简化重试队列实现：

import requests
import time
import random

def deliver_webhook(url, payload, secret, max_retries=5):
    signature = generate_signature(payload, secret)
    headers = {'X-Signature': signature, 'Content-Type': 'application/json'}
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=10)
            if 200 <= response.status_code < 300:
                return True
            elif response.status_code == 429 or 500 <= response.status_code < 600:
                # 可重试错误
                pass
            else:
                # 不可重试错误
                return False
        except requests.exceptions.RequestException:
            # 网络错误，重试
            pass
        # 带抖动的指数退避
        delay = min(30, 2 ** attempt) + random.uniform(0, 1)
        time.sleep(delay)
    return False

幂等性：处理重复传递

由于重试可能导致同一事件被多次传递，订阅者必须实现幂等处理。标准方法是在负载中包含唯一事件 ID（例如 UUID），并让接收方在一定时间内存储已处理的 ID。如果收到重复 ID，接收方确认但不重新处理。

以下是 Webhook 处理器中简单的幂等检查：

processed_events = set()

def handle_webhook(event):
    event_id = event['id']
    if event_id in processed_events:
        return 'already processed'
    # 处理事件
    processed_events.add(event_id)
    return 'success'

在生产环境中，使用持久化存储（如 Redis 或带 TTL 的数据库）来跟踪已处理的 ID。

比较：签名负载与其他安全措施

对于大多数 Webhook 用例，HMAC 签名负载在安全性和简单性之间取得了良好的平衡。

整合所有内容

要构建可靠且安全的 Webhook 系统：

• 为每个订阅者生成唯一密钥，并使用 HMAC 对每个负载进行签名。
• 在签名数据中包含时间戳和事件 ID。
• 针对暂时性故障实现带指数退避和抖动的重试。
• 在接收方使用事件 ID 确保幂等性。
• 监控传递成功率并对失败发出警报。

调试 Webhook 传递时，检查原始 HTTP 请求和响应非常宝贵。如果你正在使用 Nginx 日志追踪传入的 Webhook 请求，Nginx 日志分析器 可以帮助你解析和过滤日志条目，以识别失败的传递或可疑模式。

常见问题

什么是签名 Webhook 负载？

签名 Webhook 负载包含加密签名（通常是 HMAC），允许接收方验证请求的真实性和完整性。发送方使用共享密钥计算签名并将其包含在头部；接收方重新计算并比较。

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

常见做法是使用指数退避重试 3 到 5 次。之后，将传递标记为失败并通知订阅者。确切次数取决于你的 SLA 和事件的重要性。

为什么幂等性对 Webhook 很重要？

重试可能导致重复传递。幂等性确保多次处理同一事件与处理一次的效果相同，防止数据损坏或重复操作。