Webhook 与回调

服务器主动 POST 到客户端注册 URL 的"反向 API"——事件发生时实时推送,替代低效轮询。HMAC 签名防伪造,重试+幂等去重保证可靠性。几乎所有 SaaS 平台(GitHub、Stripe、Grafana)都提供 webhook 集成。

概述

Webhook 是服务器主动 POST 到客户端注册 URL 的"反向 API"——事件发生时实时推送，替代低效的轮询。核心安全机制是 HMAC 签名验证（防止伪造），核心可靠性机制是重试 + 幂等去重。几乎所有 SaaS 平台（GitHub、Stripe、Grafana）都提供 webhook。DingTalk/WeChat 机器人 webhook 是 IM 应用的常见集成点。

原理

Webhook = 服务器主动 POST 到客户端注册的 URL (用户定义的 HTTP callback):

传统 Polling:  Client → GET /api/status (每 30s) → 浪费, 延迟
Webhook:       Server → POST https://client/hook (事件发生时) → 实时, 零轮询

Payload + Signature:
  POST /hook HTTP/1.1
  Content-Type: application/json
  X-Signature-256: sha256=3a2b1c...
  X-Delivery: uuid-1234  ← 唯一事件 ID, 去重用

  {"event":"alert","status":"firing"}

HMAC 签名验证

接收方验证: 用共享 secret 计算 HMAC(payload_body, secret) → 比对 header。不匹配 → 拒绝 (伪造或中间人篡改)。

重试策略

非 2xx 响应 → 指数退避重试 (5s, 25s, 125s, ...)。多次失败 → disable webhook。

去重: delivery UUID → 记录已处理的事件 ID → 重复 → skip。幂等操作 (多次执行相同 effect) 是更好的保证。

Grafana → DingTalk webhook

POST https://oapi.dingtalk.com/robot/send?access_token=<token>
Content-Type: application/json

{
  "msgtype": "actionCard",
  "actionCard": {
    "title": "CPU high on li-home-0",
    "text": "### Alert\n- Instance: li-home-0\n[View](https://grafana.liz6.com/...)",
    "singleTitle": "View",
    "singleURL": "https://grafana.liz6.com/d/..."
  }
}

Grafana 内置 dingding channel 的 singleURL 硬编码指向 Grafana 自身 → 改为 webhook 自定义 actionCard → singleURL 指向 Loki drilldown。

参考

• Grafana: grafana.com/docs/grafana/latest/alerting/configure-notifications
• DingTalk: open.dingtalk.com

Keywords: webhook, HMAC, idempotency, retry, Grafana, DingTalk, signature