テーマ
イベント Webhook(SISA から送る・API・MCP オプション)
アラートが届いた・インシデントが開いた・報告書を作成した、などのイベントの通知を、SISA から登録した URL へ送る仕組みです。通知を受け取ったタイミングで、AI エージェントやプログラムを動かせます。通知に入っている ID を使えば、External API や MCP で中身を取りに行けます。
- Webhook はきっかけ、API・MCP は道具です。数分おきに API を見に行く代わりに、起きたときだけ動けます
- 送信は API コールに数えません(テスト送信も)。受けた側が API を呼べば、その呼び出しは通常どおり数えます
- 使える組織: Basic・Business・Premium で API・MCP オプションを契約している組織(Sponsor は契約なしで使えます)
「Alert Webhook API」とは向きが逆です
Alert Webhook API(監視ユニットの「Webhook API Key」)は、センサーや機器から SISA へアラートを送る受け口です(無料)。このページのイベント Webhook は、SISA からお客様のシステムへイベントを送ります。
送るイベント
| 種類 | いつ |
|---|---|
alert.received | 監視ユニットにアラートが届いた(Alert Webhook API・受信用メール)。クールダウンで受け付けなかったアラートは送りません |
incident.opened | インシデントが開いた(アラートから起票・手で起票) |
incident.resolved | インシデントを解決した |
incident.closed | インシデントを完了した |
incident.reopened | 解決から対応中に戻した |
report.created | 対応報告書ができた |
ping | console の「テスト送信」 |
送り先ごとに、送るイベントを選べます。プロジェクトで絞ることもできます(選ばなければ組織全体)。
送る中身
POST で JSON を送ります。中身は薄く、取りに行くかを決めるのに要るものと、辿るための ID だけを入れます。人の名前(担当者・操作した人)は入れません。必要なら API で取ってください。
json
{
"id": "iev_0196f3a1c2d34e5f8a9b0c1d2e3f4a5b",
"type": "alert.received",
"created_at": "2026-11-20T01:23:45Z",
"api_version": "2026-11",
"organization_id": "org_…",
"data": {
"alert_id": "ae_…",
"project_id": "pj_…",
"project_name": "○○ビル解体工事",
"situation_unit_id": "su_…",
"situation_unit_name": "3F 分電盤",
"title": "温度が上限を超えました",
"severity": "high",
"console_url": "https://console.sisa.jp/orgs/org_…/pjs/pj_…/sus/su_…",
"api_url": "https://api.sisa.jp/v1/alerts/ae_…"
}
}| 項目 | 入るイベント | 辿る先 |
|---|---|---|
id(iev_) | すべて | 重複を除くのに使う(再送しても同じ) |
organization_id(org_) | すべて | API キーの組織 |
data.project_id(pj_) | すべて | GET /v1/projects/{id} |
data.situation_unit_id(su_) | すべて(監視ユニットの無い手動のインシデントは null) | GET /v1/situation-units/{id} |
data.alert_id(ae_) | alert.received・アラートから開いた incident.* | GET /v1/alerts/{id} |
data.incident_id(inc_) | incident.*・report.created | GET /v1/incidents/{id} |
data.report_id(res_) | report.created | GET /v1/reports/{id} |
data.status | incident.* | 送った時点の状態 |
data.api_url | すべて(ping を除く) | そのイベントの中身を取る URL |
- 中身はイベントが起きた時点のものです。最新の状態は API で取ってください
- 項目は増えることがあります(知らない項目は読み飛ばしてください)。項目を消すときは
api_versionを上げます
ヘッダー
| ヘッダー | 内容 |
|---|---|
X-SISA-Signature | 署名(次の節) |
X-SISA-Event | イベントの種類(alert.received など) |
X-SISA-Event-Id | 本文の id と同じ |
User-Agent | SISA-Webhooks/1.0 (+https://docs.sisa.jp/api/webhooks) |
署名を確かめる
送り先を追加すると、console に署名の秘密(whsec_…)が 1 回だけ表示されます。受け取る側に保存してください。
X-SISA-Signature: t=1763601825,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdv1=HMAC-SHA256(秘密, "<t>.<受け取った本文そのまま>")の 16 進tが今から 5 分より離れていたら受け付けないでください(盗み見た本文の再送を防ぐ)- 秘密を作り直した後の 24 時間は、
v1=が 2 つ並びます(新しい秘密と古い秘密)。どれか 1 つが合えば本物です - 本文は JSON として読み直す前のバイト列で計算してください(整形し直すと合いません)
Alert Webhook API の署名とは形が違います
Alert Webhook API の X-Sisa-Signature-256: sha256=<hex>(本文だけで計算)とは別の形です。検証のコードを流用しても通りません。
Node.js
js
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.SISA_WEBHOOK_SECRET; // whsec_…
const app = express();
app.post("/sisa-webhook", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-SISA-Signature") ?? "";
const parts = header.split(",").map((p) => p.split("="));
const t = parts.find(([k]) => k === "t")?.[1];
const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => v);
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${t}.`)
.update(req.body) // Buffer(受け取ったまま)
.digest("hex");
const ok = sigs.some(
(s) => s.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)),
);
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body.toString("utf8"));
res.sendStatus(204); // 先に 2xx を返し、重い処理は後で
queue.push(event);
});Python
python
import hashlib, hmac, json, os, time
from flask import Flask, request, abort
SECRET = os.environ["SISA_WEBHOOK_SECRET"].encode() # whsec_…
app = Flask(__name__)
@app.post("/sisa-webhook")
def sisa_webhook():
body = request.get_data() # 受け取ったままのバイト列
parts = [p.split("=", 1) for p in request.headers.get("X-SISA-Signature", "").split(",")]
t = next((v for k, v in parts if k == "t"), None)
if t is None or abs(time.time() - int(t)) > 300:
abort(400)
expected = hmac.new(SECRET, t.encode() + b"." + body, hashlib.sha256).hexdigest()
if not any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts):
abort(400)
event = json.loads(body)
enqueue(event) # 先に 2xx を返し、重い処理は後で
return "", 204届け方
- 少なくとも 1 回届けます。同じイベントが 2 回届くことがあるので、
idで重複を除いてください。順番は保証しません(created_atで並べてください) - 成功は 5 秒以内に 2xx を返したときです。それ以外(タイムアウト・4xx・5xx・3xx のリダイレクト)は失敗として再送します。リダイレクト先へは送りません
- 再送: 1・2・4・8・16・32・60・60・60 分の間隔で、約 4 時間・10 回まで。尽きたら失敗として console の「配送の記録」に残ります(1 件ずつ再送できます)
- 1 つの送り先へは毎分 60 件まで送ります(超えた分は捨てずに少し後で送ります)
- 1 つの組織の送り先は 5 つまでです
- 応答の本文は読みません(失敗のときだけ先頭 1 KB を記録します)
止まるとき
| 状態 | いつ | 戻し方 |
|---|---|---|
| 停止中 | console で「停止」した | console で「再開」 |
| 停止中(オプション切れ) | API・MCP オプションが終わった(解約の期末・Lite への変更など) | オプションが戻ると自動で再開 |
| 停止中(24 時間届かず) | 24 時間続けて届かなかった(owner・admin にメールが届きます) | 送り先を直し、「テスト送信」で確かめてから「再開」 |
止まっている間のイベントは、再開した後にさかのぼって送りません(再開した瞬間に溜まった分が押し寄せないように)。取りこぼした分は API で取れます(報告書は GET /v1/reports?updated_since=…、インシデントは GET /v1/incidents?status=in_progress など)。
送り先の決まり
安全のため、送れる URL を絞っています。
https://で始まる URL だけ(ポートは 443 だけ)。証明書は確かめます- ホスト名で指定してください(IP アドレスの直書きは使えません)
- 名前を引いた先が、社内・ループバック・リンクローカル(クラウドのメタデータ)などインターネットの外のアドレスなら送りません。引いた結果が 1 つでもそうなら送りません
- URL に利用者名・パスワードは入れられません
管理(console)
console の「API キー」画面の「イベント Webhook」で、組織の owner・admin が管理します。
- 送り先の追加(URL・送るイベント・プロジェクトで絞る)→ 署名の秘密を 1 回だけ表示
- テスト送信(
ping)— 結果(応答コードと時間)をその場で表示 - 配送の記録(直近 30 日・100 件まで)— 失敗したものは 1 件ずつ再送
- 停止・再開・削除・秘密を作り直す(古い秘密も 24 時間は署名に並べます)
- 送り先を追加・変更すると、組織の owner・admin にお知らせのメールが届きます
AI エージェントの組み方(例)
「アラートが来たら、重さを判断して担当に知らせる」エージェントの流れです。
alert.receivedを受け、署名とidの重複を確かめて、すぐ204を返すGET /v1/alerts/{alert_id}でアラートの中身(説明・届いた時刻・起票済みか)を取る(1 コール)- 必要なら
GET /v1/situation-units/{situation_unit_id}や、同じ監視ユニットの過去のインシデント(GET /v1/incidents?…)を見る - 判断して、自社のチャットや当番表へ知らせる。インシデントになったら
incident.openedが届くので、そこから対応を追う
MCP で動くエージェントなら、受けた通知(data.api_url や ID)をそのまま渡すと、MCP の道具で中身を取りに行けます。
コール数の目安
5 分おきに見に行くと月およそ 26,000 コールですが、イベント Webhook で「起きたときだけ 1〜3 コール」にすると、多くの現場では基本料に含まれる回数に収まります。