テーマ
Alert Webhook API
外部のセンサー・IoT機器・監視サービスから、SISAへアラートを送るためのWebhook API(/alert)です。
Alert Webhook APIはAPI・MCP オプション(有料)とは異なり、追加料金なしで利用できます (公開APIの月間コール数上限の対象外・回数を気にせず呼び出せます)。プロジェクト・インシデントなどを操作する有料のExternal APIとは別のAPIです。
エンドポイント
POST https://api.sisa.jp/alert認証
リクエストヘッダーに、対象の監視ユニット(SU)ごとに発行されるWebhook API Keyを指定します。
Authorization: Bearer <SUのWebhook API Key>Webhook API Keyは監視ユニットの作成時に自動で発行され、consoleの監視ユニット詳細画面で確認できます。キーが不正・未指定の場合は 401 Unauthorized({"error": {"code": "UNAUTHORIZED", "message": "..."}, "request_id": "..."})が返ります。
署名検証
監視ユニットは、作成した時点で署名検証が有効になっています。有効な監視ユニットには、送信内容の改ざんやなりすましを防ぐため、以下のヘッダーが必須です。
有効・無効は、コンソールの監視ユニット詳細画面の「Webhook署名」で確認でき、編集画面の「Webhook署名を確認する」で変更できます(モバイルアプリやExternal APIからも変更できます)。署名を付けられない機器のときだけ無効にしてください。
X-Sisa-Signature-256: sha256=<署名>署名は、リクエストボディの生バイト列に対する HMAC-SHA256 を、Webhook API Keyを鍵として計算した16進文字列です。
signature = HMAC-SHA256(key = Webhook API Key, message = リクエストボディの生バイト列)実装上の注意
JSONは一度だけシリアライズし、その同じ文字列(バイト列)を署名の計算にも送信にも使ってください。HTTPクライアントやライブラリが送信直前に本文を再エンコードすると、送った内容と署名の対象がずれて検証に失敗することがあります。下のサンプルコードもこの順序を守っています。
署名検証を有効にしている監視ユニットに対して、ヘッダーが無い・不正な場合も 401 Unauthorized になります。
署名ヘッダーを付け忘れたとき
署名検証が有効なのに X-Sisa-Signature-256 ヘッダーが無い場合は、error.code が WEBHOOK_SIGNATURE_MISSING の 401 が返ります(鍵は合っています。足りないのは署名です)。鍵が違う場合や署名の値が一致しない場合は、従来どおり error.code が UNAUTHORIZED で、どちらが違うかは返しません。
リクエストボディ
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
situation_unit_id | string | ○ | アラートの対象となる監視ユニットのID |
level | string | ○ | 深刻度。low / medium / high / critical のいずれか |
title | string | ○ | アラートのタイトル(1〜255文字) |
description | string | ○ | アラートの詳細説明(1〜1000文字) |
レスポンス
| フィールド | 型 | 説明 |
|---|---|---|
alert_event_id | string | null | 作成されたアラートイベントのID(ae_で始まる文字列)。クールダウンで抑制された場合はnull |
status | string | created(作成された)または skipped_cooldown(下記参照) |
auth_status.api_key | string | 認証結果(verified) |
auth_status.hmac_signature | string | 署名の検証結果。verified / missing / invalid / skipped |
warnings | array | 警告(通常は空配列) |
cooldown_seconds | integer | この監視ユニットに設定されているクールダウンの秒数(0はクールダウンなし) |
retry_after_seconds | integer | null | skipped_cooldownのときだけ値が入ります。次のアラートが受け付けられるまでの残り秒数(切り上げ)。createdのときはnull |
レスポンス例
json
{
"alert_event_id": "ae_01a0933c8f1e7d2b9c4a5e6f7a8b9c0d",
"status": "created",
"auth_status": {
"api_key": "verified",
"hmac_signature": "verified"
},
"warnings": [],
"cooldown_seconds": 60,
"retry_after_seconds": null
}エラーのレスポンス
エラー(401・422 など)は、次の形で返ります。原因の種類は error.code で見分けてください (message の文言は変わることがあります)。
json
{
"error": {
"code": "WEBHOOK_SIGNATURE_MISSING",
"message": "Webhook signature header (X-Sisa-Signature-256) is missing. ..."
},
"request_id": "req_25b1f9f33f174d019d6e5839513d7080"
}| HTTP | error.code | 意味 |
|---|---|---|
| 401 | UNAUTHORIZED | Webhook API Keyが違う、または署名の値が一致しない |
| 401 | WEBHOOK_SIGNATURE_MISSING | 署名検証が有効なのに署名ヘッダーが無い |
| 422 | VALIDATION_ERROR | リクエストボディの項目が足りない・値が範囲外(level の綴りなど) |
クールダウン(連続アラートの抑制)
同じ監視ユニットから短時間に何度もアラートが送られた場合、直前の通知から一定時間(既定60秒)以内のリクエストは新しいアラートイベントを作らず、status: "skipped_cooldown" を返します。この場合も HTTPステータスは200で、エラーとしては扱われません。連続送信自体を止める必要はありません。
クールダウンは、最後にアラートイベントが作られた時刻から数えます。スキップされたリクエストでクールダウンが延びることはありません。
json
{
"alert_event_id": null,
"status": "skipped_cooldown",
"auth_status": {
"api_key": "verified",
"hmac_signature": "verified"
},
"warnings": [],
"cooldown_seconds": 60,
"retry_after_seconds": 23
}スキップされた内容を後から確実に届けたい場合は、retry_after_seconds の秒数だけ待ってから送り直してください。成功時(created)にも cooldown_seconds が返るので、次の送信をその秒数だけ控えれば、最初からスキップされずに済みます。
retry_after_seconds は「遅くともこの秒数後」
同じ監視ユニットへは、ほかの機器やメール経由でもアラートが届くことがあります。送る側が自分で秒数を数えるより、retry_after_seconds を使うのが確実です。また、元のアラートからインシデントが起票されると、クールダウンはこの秒数より早く解けることがあります。
利用制限
/alert は公開APIの月間コール数上限や、API・MCP オプションのレート制限の対象外です。安全に関わる通知を止めないための設計です。呼び出し回数を気にせず、検知したタイミングでそのまま送信してください。
SDKについて
SISAはJavaScript・Python・Go・Rust・C++・Arduino(ESP32/ESP8266)向けの公式クライアントSDKを用意しています (現在OSS公開の準備中です)。SDKを使うと、ここまでで説明した「JSONを1回だけシリアライズし、同じ文字列を署名と送信の両方に使う」という手順を意識せず、SDKが内部で正しく処理してくれます。
SDKの公開までは、以下のサンプルコードを参考に直接HTTPリクエストを組み立ててください。どの言語でも考え方は同じです。
- リクエストボディをJSON文字列として1回だけ組み立てる
- その文字列(バイト列)に対してHMAC-SHA256で署名を計算する(署名検証を有効にしている場合)
- 同じ文字列をそのままリクエストボディとして送信する
cURL
bash
curl -X POST https://api.sisa.jp/alert \
-H "Authorization: Bearer <SUのWebhook API Key>" \
-H "Content-Type: application/json" \
-d '{
"situation_unit_id": "su_xxxxxxxxxxxx",
"level": "high",
"title": "温度異常を検知",
"description": "現場の気温がしきい値を超えました"
}'Node.js(標準ライブラリのみ)
javascript
const crypto = require("node:crypto");
const apiKey = "<SUのWebhook API Key>";
const body = JSON.stringify({
situation_unit_id: "su_xxxxxxxxxxxx",
level: "high",
title: "温度異常を検知",
description: "現場の気温がしきい値を超えました",
});
// 署名検証を有効にしている場合のみ必要
const signature = crypto.createHmac("sha256", apiKey).update(body).digest("hex");
const res = await fetch("https://api.sisa.jp/alert", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"X-Sisa-Signature-256": `sha256=${signature}`,
},
body, // JSON.stringify した文字列をそのまま送る(再エンコードしない)
});
console.log(await res.json());Python(標準ライブラリのみ)
python
import hmac
import hashlib
import json
import urllib.request
api_key = "<SUのWebhook API Key>"
body = json.dumps({
"situation_unit_id": "su_xxxxxxxxxxxx",
"level": "high",
"title": "温度異常を検知",
"description": "現場の気温がしきい値を超えました",
}).encode("utf-8")
# 署名検証を有効にしている場合のみ必要
signature = hmac.new(api_key.encode("utf-8"), body, hashlib.sha256).hexdigest()
req = urllib.request.Request(
"https://api.sisa.jp/alert",
data=body, # json.dumps した同じバイト列をそのまま送る
method="POST",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-Sisa-Signature-256": f"sha256={signature}",
},
)
with urllib.request.urlopen(req) as res:
print(res.read())