Webhook 详解:签名载荷与重试机制

Backend2026-11-14TryQuickToolBox

你已经构建了一个 API,现在需要在事件发生时通知其他服务。轮询效率低下,因此你实现了 Webhook。但很快你意识到:如何确保载荷是真实的?如果接收方宕机了怎么办?如果没有适当的保护措施,Webhook 可能会成为安全漏洞和可靠性噩梦。

在本文中,我们将介绍 Webhook 的基本要点,重点讨论两个关键方面:用于安全的签名载荷和用于可靠性的重试机制。我们将提供实用的代码示例和最佳实践,帮助你构建健壮的 Webhook 系统。

什么是 Webhook?

Webhook 是用户定义的 HTTP 回调。它们允许一个系统在特定事件发生时向另一个系统发送实时数据。与需要你拉取数据的 API 不同,Webhook 将数据推送给您。这使得它们非常适合事件驱动的架构。

常见用例包括支付通知(例如 Stripe)、CI/CD 触发器(例如 GitHub)和消息平台(例如 Slack)。发送方向接收方提供的 URL 发起 HTTP POST 请求,载荷包含事件详情。

为什么使用签名载荷保护 Webhook 安全?

Webhook 端点是公开可访问的,容易受到欺骗攻击。攻击者可以发送伪造的载荷来触发非预期的操作。为了防止这种情况,发送方使用共享密钥对载荷进行签名。接收方验证签名以确保真实性和完整性。

签名通常涉及使用密钥对载荷生成 HMAC(基于哈希的消息认证码)。签名在头部(例如 X-Signature)中发送。接收方重新计算 HMAC 并与接收到的签名进行比较。

如何实现签名载荷

让我们看一个使用 Flask 的 Python 简单示例。发送方计算签名:

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

接收方验证签名:

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
secret = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # Process payload
    return '', 200

最佳实践:

实现可靠的重试

Webhook 传递可能因网络问题、接收方宕机或处理错误而失败。健壮的系统应使用指数退避重试失败的传递。

重试策略

常见方法:最多重试 N 次,延迟逐渐增加(例如 1秒、5秒、30秒、5分钟、30分钟)。耗尽重试后,将传递标记为失败并发出警报。

以下是使用 requests 库和 tenacity 的 Python 简单重试机制:

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

重试最佳实践:

比较:签名载荷 vs. 基本认证

方法安全性复杂性重放保护
基本认证低(每次发送凭证)低无
签名载荷 (HMAC)高中有(带时间戳)

分步指南:构建带重试的 Webhook 发送器

  1. 定义事件载荷,包含唯一事件 ID 和时间戳。
  2. 计算签名,使用 HMAC-SHA256 对原始请求体进行签名。
  3. 发送请求,在头部中包含签名。
  4. 处理失败,通过指数退避重试。
  5. 记录传递并提供可见性。

测试 Webhook

使用 ngrok 等工具暴露本地服务器并测试 Webhook 传递。在测试中始终验证签名以及早发现问题。

常见问题

Webhook 中的签名载荷是什么?

签名载荷是发送方使用共享密钥生成加密签名(通常为 HMAC)的 Webhook 请求。接收方验证签名以确认请求是真实的且未被篡改。

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

没有固定次数,但常见做法是使用指数退避重试 3 到 5 次。考虑接收方的典型停机时间和事件的关键性。始终允许手动重试。

我可以使用 JWT 进行 Webhook 签名吗?

可以,但更复杂。HMAC 签名更简单,在大多数情况下足够。如果需要包含声明,JWT 可能合适。

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