モニタリングツールから署名付きウェブフックアラートを設定する方法

ウェブフックアラートは、アップタイムモニターをその他すべての機能（PagerDuty、Opsgenie、内部インシデント管理システム、チケットトラッカー、カスタムSlackボット）に接続する統合用の接着剤です。基本的なメカニズムはシンプルです（インシデントが発生したときにモニターがJSONをエンドポイントにPOSTします）。詳細（シグネチャ検証、再試行動作、べき等性）は実装がより興味深くなる部分です。このガイドは実践的なセットアップについて説明します。

メールやSlackではなくウェブフックを使用する理由

メールとSlackは人間にとっては問題なく機能します。ウェブフックはシステムに対して機能します。3つのユースケースが追加のセットアップを正当化します。

オンコール当番制を実行するページングツール（PagerDuty、Opsgenie）へのルーティング。チケットをオープンしたり、Slackスレッドを作成したり、ランブックを自動的に実行する内部インシデント管理システムの駆動。自動化された復旧をトリガーする（ワーカーの再起動、クラスターのスケールアップ、バックアップリージョンへのフェイルオーバー）。3つすべてが構造化されたペイロード、再試行安全な配信、認証が必要です。ウェブフックはすべて3つを提供しますが、メールとSlackは何も提供しません。

想定されるペイロード形式

ほとんどのモニタリングツールはインシデントイベント時に同様のJSONペイロードを送信します。正確なフィールド名は異なりますが、4つのセクションが標準的です。

• event: 「monitor.down」または「monitor.up」で、エンドポイントがオープンとクローズをルーティングできるようにする。
• monitor: id、name、type、target、last status。何が壊れているかを特定するのに十分なコンテキスト。
• check: ステータスコード、レスポンスタイム、エラーメッセージ。診断の詳細。
• timestamp: ISO 8601、UTC。順序付けと重複排除に重要。

Verifying the HMAC signature

Any webhook endpoint exposed to the public internet needs signature verification. Without it, an attacker who guesses your URL can fake a 'monitor down' event and trigger your remediation, your paging, and your support response. With HMAC verification, only your monitoring tool can sign valid payloads.

The pattern: the monitoring tool sends an X-Monitorah-Signature header with the HMAC-SHA256 of the raw request body, keyed with a shared secret. Your endpoint recomputes the HMAC of the body using the same secret, compares (in constant time) to the header value, rejects on mismatch. Use the raw bytes of the body for the HMAC, not the parsed JSON: a single whitespace difference produces a different signature.

Retry and idempotency

Webhook delivery is best-effort, not guaranteed. Two patterns make your endpoint robust to retries and partial failures.

• Honour retries gracefully. Most monitors will retry a 5xx response with exponential backoff for up to 24 hours. Return a 5xx if you cannot process the event; return a 2xx if you can.
• Treat the event id as an idempotency key. The same incident open can fire the webhook twice during a network blip. Deduplicate by storing the event id and skipping if you have already processed it.
• Respond quickly. Take less than 5 seconds to return a 2xx, even if your downstream processing takes longer. Use a job queue if needed.

Integrating with PagerDuty

PagerDuty accepts a generic webhook through its Events API v2. The flow: your monitoring tool POSTs a custom JSON payload to your own handler. Your handler verifies the HMAC, maps the payload into PagerDuty's expected schema, and POSTs to PagerDuty's events endpoint with your routing key.

The translation layer is the right place to add deduplication, escalation rules, and per-monitor routing keys. PagerDuty's UI handles the rotation once the event has been ingested. Keep the translator simple. The cleanest version is fewer than a hundred lines of code.

A starter webhook handler in 20 lines

The pattern: receive POST, extract X-Monitorah-Signature header, HMAC-SHA256 the raw body with your shared secret, constant-time compare with the header. If they match, parse JSON, deduplicate by event id, dispatch. If they do not match, return 401 without processing. This handler is the building block for every integration on top: PagerDuty, Opsgenie, Slack bots, internal incident systems. Once it is in place, every new integration is a few lines of dispatch logic and nothing more.