Webhooks

Webhook（ウェブフック） は、dAio をお客様独自のシステムと連携させます。プラットフォームを継続的にポーリングする代わりに、dAio から通知を受け取るようにします。イベントが発生した瞬間 — 気象アラートの発報、高リスクの検知 — に、dAio は署名付きの HTTP リクエストをリアルタイムでお客様が選択したエンドポイントへ送信します。これによりワークフローを自動化できます。チケットの起票、社内通知、業務ダッシュボードの更新、または現場の対応計画の起動などです。

これは dAio のアラートとお客様の情報システムとを結ぶ橋渡しです。

ヒント : まずは 1 つのイベント種別を購読する単一の Webhook から始め、チェーンをエンドツーエンドで検証してから拡張してください。処理を信頼できる状態にする前に、システムを通知で溢れさせてしまうのを避けられます。

Webhook を設定する

1. 設定 > Webhooks にアクセスします。
2. 新しい Webhook をクリックします。
3. 宛先 URL を入力します。お客様のサーバーの HTTPS エンドポイントです（例: https://votre-serveur.com/webhook）。
4. 対応するラベルをクリックして、リッスンするイベントを選択します。
5. 作成で確定します。

作成時にシークレットが自動生成されます。これは各リクエストを HMAC-SHA256 で署名するために使われます（下記参照）。サーバー側で保管してください。各呼び出しが本当に dAio から来たものであることを検証できます。

注意 : URL は HTTPS であり、かつ公開アクセス可能でなければなりません。単純な HTTP のエンドポイントや、閉じたファイアウォールの内側にあるエンドポイントは配信を受信できません。

利用可能なイベント

イベント	説明
weather.alert	あるサイトで気象アラートが発報されました
weather.threshold	カスタムの気象しきい値を超過しました
air_quality.alert	大気質アラートが発行されました
pollen.alert	花粉アラートが発行されました
marine.alert	海洋状況アラートが発行されました
frost.alert	霜アラートが発報されました
storm.alert	雷雨／暴風アラートが発報されました
business.risk_high	お客様の事業活動に対して高リスクレベルが検知されました

ヒント : 各 Webhook は、受信側システムが実際に活用するイベントだけを購読させてください。「チケット」エンドポイントは「ダッシュボード」エンドポイントと同じイベントを受け取る必要はありません。

ペイロードの形式

各配信は、本文が JSON オブジェクトである POST リクエストです。一般的な構造は次のとおりです。

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

event フィールドはイベント種別を識別し、timestamp は発行日時を示し（UTC、ISO 8601 形式）、data にはイベント固有の詳細が含まれます。

HMAC-SHA256 認証

各リクエストは、お客様のシークレットを用いて HMAC-SHA256 で署名されます。署名は X-Daio-Signature ヘッダーに、sha256=<signature> の形式で送信されます。

リクエストを処理する前に、この署名を必ず検証してください。これが、呼び出しが dAio から来たものであり、ペイロードが改ざんされていないことを保証します。

サーバー側での検証（Python）:

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

注意 : 署名は、JSON のデシリアライズを行う前に、リクエストの生の本文（受信したバイト列）に対して計算してください。わずかな再フォーマットでもハッシュが変わり、検証に失敗します。

テストとデバッグ

• Webhook の横にあるテストアイコン（▶）をクリックすると、ダミーのイベントをお客様のエンドポイントへ送信できます。
• HTTP 2xx の応答は、お客様のサーバーがリクエストを受信し受理したことを示します。
• Webhook を展開すると、その直近の配信を確認できます。HTTP コード、イベント種別、タイムスタンプです。
• 色付きのドットが Webhook の状態を示します。緑 = 有効、赤 = 繰り返しの失敗により無効化。

配信履歴

すべての送信が記録されます。Webhook を展開すると、各試行について次が表示されます。

• 応答の HTTP コード（300 未満なら緑、それ以外は赤）
• 配信されたイベント種別
• 試行の日時

配信が失敗すると、Webhook に失敗カウンターが表示されます。

再試行と信頼性

dAio は失敗時に、間隔を徐々に広げながら自動的に配信を再試行します。したがって、お客様のエンドポイントは**冪等（idempotent）**でなければなりません。同じ配信が複数回届くことがあり、お客様の処理は副作用なしに同じ結果を生成しなければなりません。

注意 : お客様のエンドポイントは 10 秒以内に HTTP 2xx コードで応答しなければなりません。それを超えた場合、またはエラーコードの場合、配信は失敗とみなされ再試行されます。繰り返しの失敗の後、Webhook は自動的に無効化されます。

ベストプラクティス

• 常に HMAC 署名を検証してからペイロードを処理してください。認証されていないリクエストを決して信頼しないでください。
• すばやく応答する: ただちに 200 を返し、その後ワークロードをバックグラウンドで処理してください。タイムアウトや不要な再試行を避けられます。
• 処理を冪等にすることで、複数回の配信を安全に受け止められます。
• 発生源でフィルタリングする: 各 Webhook は、その受信側システムに有用なイベントだけを購読させてください。
• 失敗カウンターと配信履歴を監視し、エンドポイントが無効化される前に故障を素早く検知してください。
• お客様側で変更（デプロイ、URL 変更）を行うたびに、テストボタンを使用し、実際のイベントを待たずにチェーンを検証してください。

ヒント : Webhook をアラートとチームの設定と組み合わせて、適切な情報を適切なシステムへ自動的に振り分けてください。Webhook の利用可否はお客様のサブスクリプションに依存します。