Webhook API
Webhook 用於接收系統事件通知，包含告警觸發、設備上下線等即時事件。
💡 每個用戶只能設定一個 Webhook 端點。
端點概覽
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/users/me/webhook | 取得 Webhook 設定 |
| POST | /api/v1/users/me/webhook | 建立 Webhook 設定 |
| PATCH | /api/v1/users/me/webhook | 更新 Webhook 設定 |
| DELETE | /api/v1/users/me/webhook | 刪除 Webhook 設定 |
| POST | /api/v1/users/me/webhook/test | 測試 Webhook |
| GET | /api/v1/users/me/webhook/secret | 取得 Webhook 密鑰 |
| POST | /api/v1/users/me/webhook/secret/regenerate | 重新產生密鑰 |
| GET | /api/v1/users/me/webhook/deliveries | 查詢投遞紀錄 |
使用場景
- 即時通知：告警觸發時即時推送到您的伺服器
- 系統整合：與 Slack、Teams、PagerDuty 等整合
- 自動化：觸發自動化工作流程
建立 Webhook 設定
POST /api/v1/users/me/webhook
請求參數
| 參數 | 型別 | 必填 | 範圍/限制 | 說明 |
|---|---|---|---|---|
url | String | ✅ | HTTPS URL，最大 500 字元 | Webhook URL |
name | String | ❌ | 最大 100 字元 | 顯示名稱 |
secret | String | ❌ | 16-128 字元 | 簽名密鑰（不填則自動產生） |
subscribedTypes | String[] | ❌ | 見下方 | 訂閱事件類型（不填則訂閱全部） |
timeoutMs | Number | ❌ | 1000-30000 | 請求超時（毫秒），預設 5000 |
maxRetries | Number | ❌ | 0-5 | 失敗重試次數，預設 3 |
事件類型 (subscribedTypes)
| 值 | 說明 |
|---|---|
analysis_started | 分析開始 |
analysis_stopped | 分析停止 |
analysis_error | 分析錯誤 |
alert_triggered | 告警觸發 |
device_offline | 設備離線 |
device_online | 設備上線 |
device_analysis_error | 設備分析錯誤 |
node_offline | 計算節點離線 |
node_online | 計算節點上線 |
node_error | 計算節點錯誤 |
quota_warning | 配額警告 (80%) |
quota_exceeded | 配額超限 (100%) |
billing_cycle_completed | 帳單週期完成 |
maintenance_scheduled | 計劃性維護通知 |
system_announcement | 系統公告 |
請求範例
{
"url": "https://your-server.com/webhook/saas",
"name": "主要通知 Webhook",
"subscribedTypes": [
"alert_triggered",
"device_offline",
"analysis_error"
],
"timeoutMs": 5000,
"maxRetries": 3
}
Webhook 請求格式
當事件發生時，系統會發送 POST 請求：
HTTP 標頭
| 標頭 | 說明 |
|---|---|
Content-Type | application/json |
X-SaaS-Signature | sha256=... HMAC-SHA256 簽名 |
X-SaaS-Timestamp | Unix 時間戳 |
X-SaaS-Event | 事件類型 |
X-SaaS-Delivery-Id | 投遞 ID |
Payload 結構（告警觸發範例）
{
"id": "event-uuid",
"type": "alert_triggered",
"timestamp": "2026-01-29T10:30:00Z",
"data": {
"ruleId": "rule-uuid",
"ruleName": "排隊人數過多警報",
"sceneId": "scene-uuid",
"sceneName": "櫃台排隊監控",
"deviceId": "device-uuid",
"severity": "warning",
"metricPath": "current.inQueue",
"operator": "GT",
"threshold": 10,
"actualValue": 15,
"message": "排隊人數 (15) 超過閾值 (10)",
"snapshotUrls": ["https://storage.example.com/snapshot.jpg"]
}
}
簽名驗證
使用 secret 驗證請求來源：
const crypto = require('crypto');
function verifyWebhook(payload, signature, timestamp, secret) {
const message = `${timestamp}.${JSON.stringify(payload)}`;
const expected = crypto
.createHmac('sha256', secret)
.update(message)
.digest('hex');
return signature === `sha256=${expected}`;
}
查詢投遞紀錄
GET /api/v1/users/me/webhook/deliveries
查詢參數
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
page | Number | ❌ | 頁碼（預設 1） |
limit | Number | ❌ | 每頁筆數（預設 20，最大 100） |
status | String (enum) | ❌ | success / failed / pending |
deviceId | UUID | ❌ | 篩選特定設備 |
sceneId | UUID | ❌ | 篩選特定場景 |
startDate | ISO 8601 | ❌ | 起始時間 |
endDate | ISO 8601 | ❌ | 結束時間 |
響應範例
{
"data": [
{
"id": "delivery-uuid",
"webhookUrl": "https://your-server.com/webhook/luminys",
"notificationId": "notif-uuid",
"alertEventId": "alert-event-uuid",
"notificationType": "alert_triggered",
"severity": "warning",
"deviceId": "device-uuid",
"sceneId": "scene-uuid",
"payload": { "...完整通知內容": true },
"status": "success",
"httpStatusCode": 200,
"responseTimeMs": 152,
"responseBody": "{\"ok\":true}",
"errorMessage": null,
"attemptNumber": 1,
"maxAttempts": 3,
"isFinalAttempt": true,
"createdAt": "2026-01-29T10:30:05Z"
}
],
"pagination": {
"limit": 20,
"currentPage": 1,
"totalRecords": 42,
"totalPages": 3,
"nextPage": 2,
"previousPage": null
}
}
💡 投遞紀錄保留 30 天，超過自動清除。