Webhook

汎用 webhook チャネルは フォールバック です。Ongrid がネイティブに話さないチャット画面、チケッティングシステム、内製リレー（Microsoft Teams、Mattermost、Rocket Chat、OpsGenie、PagerDuty、自前ルーター）にアラートをプッシュする必要があるとき、汎用 webhook をそれに向けると、アラートパイプラインが正典の Ongrid メッセージ JSON をポストします。

専用チャネルがあるときはそれを使ってください

Slack / Feishu / DingTalk / WeCom / Telegram には、より豊かなペイロード（Slack attachments、署名）を描画する専用チャネルがあります。汎用 webhook に手を伸ばすのは、専用チャネルがないときだけ。

ペイロード

ボディは正典の notify.Message の形を JSON エンコードして逐語：

json

{
  "severity": "critical",
  "subject": "node-01 swap_high",
  "body": "swap_in_pages > 1000 for 5m",
  "source": "alert",
  "labels": {
    "rule": "swap_high",
    "incident_id": "1234",
    "device_id": "7",
    "host": "node-01"
  },
  "dedupe_key": "alert:swap_high:device=7",
  "occurred_at": "2026-05-30T14:02:35Z"
}

エンベロープなし、msgtype なし、フラット化なし。受信者はアラートパイプラインが生成したフィールドをそのまま受け取ります。 NewGenericWebhookSender が構築します。

オプションの HMAC 署名

Secret フィールドを埋めると、すべてのリクエストに X-Ongrid-Signature ヘッダーが乗ります：

text

X-Ongrid-Signature: sha256=<hex>

<hex> はポストされる 正確なバイト列 に対する hex(HMAC-SHA256(secret, body)) です。署名者は signGenericWebhook です。

受信側での検証

python

# Python receiver
import hmac, hashlib

def verify(secret, body_bytes, header):
    expected = "sha256=" + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

// Go receiver
func verify(secret string, body, header []byte) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := []byte("sha256=" + hex.EncodeToString(mac.Sum(nil)))
    return hmac.Equal(expected, header)
}

エンドポイントが公開なら常に署名を検証してください

署名なしの汎用 webhook URL は URL を知る誰にでも開かれています。署名ヘッダーが「これは Ongrid から」を認証する唯一のものです。

リクエストの形

プロパティ	値
メソッド	`POST`
`Content-Type`	`application/json`
`User-Agent`	`ongrid-notify/1.0`
ボディ	`notify.Message` の JSON
Sig ヘッダー	`X-Ongrid-Signature: sha256=…`（secret 時のみ）
タイムアウト	リクエストごとの `http.Client` タイムアウト（デフォルト 15 秒）

成功基準

Sender は HTTP 2xx（200–299）を成功として扱います。それ以外 —— 3xx リダイレクト、4xx、5xx を含む —— は unexpected status: … であり、ダンピングパイプラインで失敗配信としてカウントされます。レスポンスのボディはパースされません。Ongrid はリレーがどんな JSON をエコーバックするかは気にしません。

リトライとダンピング

リトライセマンティクスは Sender ではなく アラートパイプライン が所有します。Sender は Send(ctx, msg) 呼び出しごとに正確に 1 回だけポストします。パイプラインが決めるのは：

ダンピングウィンドウ。 ルールごと、デフォルト 5 分。同じ dedupe キーはウィンドウあたり最大 1 回発火します。
発火中の再通知。 デフォルト 1 時間。このウィンドウ後もインシデントがオープンなら、チャネルはチャット履歴に埋もれないよう再通知を受け取ります。
復旧メッセージ。 アラートがクリアしたときに発火。

Sender の仕事はバイトをプッシュすること。パイプラインの仕事はいつかを決めること。

トランスポート失敗での自動リトライなし

Sender がポストする瞬間に受信者がダウンしていれば、メッセージは 失われます（配信エラーとしてログ、チャネルごとの配信統計に表面化）。パイプラインはキューイングや後でのリトライを行いません。理由：復旧の 3 分後に配信される 5 分古いアラートは、欠落しているものより混乱を招きます。堅牢な受信者を使うか、Ongrid と不安定な下流の間に自前のキューを重ねてください。

セットアップ

POST + application/json を受け入れる HTTP エンドポイントを立てる。 Ongrid と共有する強い secret を選ぶ。
Ongrid で：Settings → Channels → New → Provider = webhook → Endpoint = あなたの URL → Secret = 共有 secret。
Test をクリック。テストメッセージは合成された notify.Message{Severity: "info", Subject: "Ongrid test", …}。受信者ログで署名ヘッダーを検証してください。

レシピ

Microsoft Teams（incoming webhook）

Teams の incoming webhook は異なるペイロード形式（MessageCard）を受け入れます。最もシンプルなパスは Ongrid と Teams の間に小さなアダプタを置くこと：

python

# server.py - listens on /ongrid-to-teams
@app.post("/ongrid-to-teams")
def relay(msg: dict):
    teams_url = os.environ["TEAMS_WEBHOOK"]
    card = {
        "@type": "MessageCard",
        "@context": "https://schema.org/extensions",
        "themeColor": {"critical":"D92F2F","warning":"F2C037","info":"36A64F"}.get(msg["severity"], "6F7A87"),
        "title": msg["subject"],
        "text": msg["body"],
    }
    requests.post(teams_url, json=card)

Ongrid webhook チャネルを https://your-relay/ongrid-to-teams に向けてください。

PagerDuty Events API v2

同じパターン：{severity, subject, body, dedupe_key} を PagerDuty events.v2 ペイロードに翻訳する小さなリレー。PD の dedup_key フィールドは Ongrid の dedupe_key に 1:1 でマップするので、Ongrid 内の同じインシデントは PD 内の同じアラートになります。

Splunk HEC / Elastic ingest

URL に Splunk トークンを含む HEC エンドポイントにチャネルを向けてください。 Splunk は正典の Ongrid JSON を受け入れます。下流検索のため severity と labels.rule でインデックスしてください。

フィールドリファレンス

真実の出所は Message を参照。安定フィールド：

フィールド	型	注記
`severity`	string	`critical` / `warning` / `info`。
`subject`	string	ルール名 + ターゲット —— 1 行。
`body`	string	複数行詳細。改行を含む可能性あり。
`source`	string	`alert` / `test` など。
`labels`	map[string]string	`rule`、`incident_id`、`device_id`、カスタム。
`dedupe_key`	string	`pipeline:rule:label-set`。アイデンティティごとに安定。
`occurred_at`	RFC3339 string	UTC。アラート evaluator が発火した瞬間。

新規フィールドは追加的 —— 受信者は未知のキーを無視すべきです。

Webhook ​

ペイロード ​

オプションの HMAC 署名 ​

受信側での検証 ​

リクエストの形 ​

成功基準 ​

リトライとダンピング ​

セットアップ ​

レシピ ​

Microsoft Teams（incoming webhook） ​

PagerDuty Events API v2 ​

Splunk HEC / Elastic ingest ​

フィールドリファレンス ​

関連 ​