Webhook とコールバック

サーバーがクライアントの登録 URL に対して積極的に POST する「逆方向 API」——イベント発生時にリアルタイムでプッシュし、非効率なポーリングに代わる。HMAC 署名による偽造防止、リトライと冪等性による重複排除で信頼性を保証。ほぼすべての SaaS プラットフォーム（GitHub、Stripe、Grafana）が Webhook 統合を提供している。

概要

Webhook は、サーバーがクライアントの登録 URL に対して積極的に POST する「逆方向 API」——イベント発生時にリアルタイムでプッシュし、非効率なポーリングに代わる。主要なセキュリティメカニズムは HMAC 署名検証（偽造防止）であり、主要な信頼性メカニズムはリトライと冪等性による重複排除である。ほぼすべての SaaS プラットフォーム（GitHub、Stripe、Grafana）が Webhook を提供している。DingTalk/WeChat ボットの Webhook は、IM アプリケーションにおける一般的な統合ポイントである。

仕組み

Webhook = サーバーがクライアントに登録された URL に対して積極的に POST する（ユーザー定義の HTTP コールバック）:

従来のポーリング:  Client → GET /api/status (30秒ごと) → リソースの無駄遣い、遅延
Webhook:       Server → POST https://client/hook (イベント発生時) → リアルタイム、ポーリング不要

ペイロードと署名:
  POST /hook HTTP/1.1
  Content-Type: application/json
  X-Signature-256: sha256=3a2b1c...
  X-Delivery: uuid-1234  ← 一意のイベント ID、重複排除用

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

HMAC 署名検証

受信側での検証: 共有シークレットを用いて HMAC(payload_body, secret) を計算し、ヘッダーと照合する。一致しない場合 → 拒否（偽造または中間者攻撃による改ざん）。

リトライ戦略

2xx 以外のレスポンス → 指数バックオフによるリトライ (5秒、25秒、125秒、...)。複数回の失敗 → Webhook を無効化。

重複排除: delivery UUID → 処理済みイベント ID を記録 → 重複検出 → スキップ。冪等操作（同じ効果を複数回実行しても問題ない）がより確実な保証となる。

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 チャンネルでは singleURL が Grafana 自身を指すようにハードコードされているため、Webhook のカスタム actionCard に変更し、singleURL を Loki のドリルダウン先に向ける。

参考

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

キーワード: webhook, HMAC, 冪等性, リトライ, Grafana, DingTalk, 署名