Webhook 详解:签名载荷与重试机制
你已经构建了一个 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
最佳实践:
- 使用强密钥并定期轮换。
- 在签名数据中包含时间戳以防止重放攻击。
- 使用
hmac.compare_digest进行恒定时间比较。 - 对原始请求体进行签名,而不是解析后的 JSON,以避免不一致。
实现可靠的重试
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 发送器
- 定义事件载荷,包含唯一事件 ID 和时间戳。
- 计算签名,使用 HMAC-SHA256 对原始请求体进行签名。
- 发送请求,在头部中包含签名。
- 处理失败,通过指数退避重试。
- 记录传递并提供可见性。
测试 Webhook
使用 ngrok 等工具暴露本地服务器并测试 Webhook 传递。在测试中始终验证签名以及早发现问题。
常见问题
Webhook 中的签名载荷是什么?
签名载荷是发送方使用共享密钥生成加密签名(通常为 HMAC)的 Webhook 请求。接收方验证签名以确认请求是真实的且未被篡改。
失败的 Webhook 应该重试多少次?
没有固定次数,但常见做法是使用指数退避重试 3 到 5 次。考虑接收方的典型停机时间和事件的关键性。始终允许手动重试。
我可以使用 JWT 进行 Webhook 签名吗?
可以,但更复杂。HMAC 签名更简单,在大多数情况下足够。如果需要包含声明,JWT 可能合适。
准备好测试你的 Webhook 载荷了吗?使用我们的 JSON 格式化工具 在发送前验证和美化你的 JSON 载荷。