Webhook 与消息推送的可靠投递

Webhook 是“至少一次”投递,重复和乱序都要自己处理。

自动化自建服务可靠性2026-01-08约 1 分钟352 字

用 Webhook 把系统事件推到消息工具,看起来只是发个 POST,实际要考虑签名、重试、重复和超时。

接收端要做三件事

  1. 验签:用共享密钥对原始请求体做 HMAC,防止伪造;
  2. 快速返回:先回 200,再异步处理,避免上游超时重发;
  3. 幂等:按事件 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。