Webhook 与消息推送的可靠投递
Webhook 是“至少一次”投递,重复和乱序都要自己处理。
用 Webhook 把系统事件推到消息工具,看起来只是发个 POST,实际要考虑签名、重试、重复和超时。
接收端要做三件事
- 验签:用共享密钥对原始请求体做 HMAC,防止伪造;
- 快速返回:先回 200,再异步处理,避免上游超时重发;
- 幂等:按事件 ID 去重,重复投递不重复执行。
python
# 伪代码:验签 + 去重
sig = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, request.headers.get("X-Signature", "")):
return 401
if seen(request.json["id"]):
return 200
enqueue(request.json)
return 200发送端要有退避
bash
for i in 1 2 3 4 5; do
code=$(curl -sS -o /dev/null -w '%{http_code}' -m 8 -X POST "$URL" -d "$PAYLOAD")
case "$code" in
2*) break ;;
429|5*) sleep $((2**i)) ;;
*) break ;;
esac
done-m 8 是必须的。没有超时的请求会卡住整个脚本,尤其在上游半死不活时。
消息内容
一条通知应包含:对象、变化、时间、影响、建议动作。只有“状态变更”四个字的消息,接收的人还得回去查。
内网回调
内网服务要接收外部 Webhook,需要公网入口。可以走隧道,或让上游支持轮询。两者都比直接映射端口安全。
上游重发很常见
超时、5xx、连接重置都会触发重发,同一事件可能到达三次。没有幂等键时,会出现重复告警、重复建单、重复扣款。
观察
记录每次投递的状态码、耗时、重试次数。连续失败率上升时,先看上游状态页,再查自己的证书与 DNS。
小结
验签、快回、去重、退避、超时。五件事做到,Webhook 才从“玩具”变成可靠通道。
说明:文中的地址、域名、主机名与账号均为脱敏示例;配置片段来自实际环境,但版本与网络条件不同,照搬前请先在测试环境验证。最后校对:2026-01-08。