第三方整合
快速整合：接收 Watch 事件
本指南適用於由 Watch 管理攝影機與監看規則、既有系統接收告警的整合方式。完成部署後，在 Web GUI 設定來源、規則與通知端點；整合端接收 Webhook，必要時再查詢事件與圖片。
部署 Docker → Web GUI 設定 → 接收事件
下載整合範例（Python 原始碼、Compose 設定、操作說明）
基本接法：在你們的後端提供 Webhook 接收端，接收 Watch 的 POST 通知。GET 查詢是選用功能，不必為了接收告警重新開發攝影機或規則設定 API。 直接看 POST / GET 接法 ↓
是否需要 RTSP 或其他 API？
RTSP 是攝影機傳送影像給 Watch 的協定。將可連線的 RTSP 位址填入 GUI 即可；事件接收端不需要處理影像串流。若 VMS 無法提供相容的 RTSP 來源，需另外確認轉接方式，不能保證所有 VMS 都能直接接入。
部署人員仍需設定模型憑證、簽章密鑰及網路允許清單；這些目前在伺服器環境設定中完成。GUI 負責日常來源、監看規則及通知端點設定。
若要從你們的產品批次管理攝影機、修改規則、控制 Watch 或內嵌操作介面，需另評估完整 API 與登入整合。本指南僅涵蓋事件通知與讀取；上線前仍需在目標現場驗證取流、模型判斷與事件送達。
會收到什麼？事件輸出與欄位
Watch 會以 HTTP POST 將事件 JSON 送到你設定的 Webhook URL。以下是異常事件的精簡範例（只列常用欄位，ID、時間與內容為示意）。
{
"id": "evt_example",
"schema": "sentinel.event.v1",
"type": "monitor.alert.raised",
"severity": "critical",
"state": "raised",
"created_at": "2026-09-07T12:00:00Z",
"source_id": "src_camera03",
"monitor_id": "mon_restricted_area",
"title": "有人進入管制區域",
"summary": "攝影機 03 偵測到有人進入指定區域。",
"evidence": {
"image_url": "/v1/events/evt_example/image"
}
}| 欄位 | 用途 |
|---|---|
| id | 事件 ID。同一事件的狀態更新可沿用此 ID。 |
| type | 發生什麼事，例如 monitor.alert.raised（監看告警）。 |
| severity | 嚴重程度：safe、suspicious、critical。 |
| state | 事件狀態：raised（發生）、updated（更新）、cleared（解除）。 |
| created_at | 事件建立時間（ISO 8601）。 |
| source_id / monitor_id | 對應的攝影機來源與監看任務；部分系統事件可為 null。 |
| title / summary | 提供人閱讀的標題與說明，不要用文字解析來判斷告警。 |
| evidence.image_url | 事件圖片位置；可能無圖片。下載需 events:read API key。 |
常見事件：monitor.alert.raised（告警發生）、monitor.alert.updated（告警更新）、monitor.alert.cleared（告警解除）、source.disconnected（攝影機斷線）、inference.failed（推論失敗）。實際接收哪些事件，由 Webhook 篩選設定決定；只勾 critical 與 raised 時，不會收到所有更新或解除通知。
接收端先驗證簽章、保存事件，再回覆 2xx。重送請依 HTTP header 的 X-Sentinel-Delivery-ID 去重，不要只用事件 id。Webhook 不會逐筆傳送普通推論。
1. 啟動 Watch 與範例接收器
先向天序取得目前的 Sentinel 原始碼部署套件，安裝 Docker Compose v2 與 Python 3。將範例壓縮檔解壓至套件根目錄，保留 deploy/ 與 docs/ 的目錄位置。以下使用 Gemini 雲端模型與一支可連線的 RTSP 攝影機；雲端模型會接收推論圖片，並使用你的 API 額度。
cd deploy/api
./bootstrap.sh cloud_gemini只在首次部署執行 bootstrap；已有 .env 就保留。編輯 .env，填入以下設定，攝影機 IP 與連接埠請換成現場值。保留程式產生的 API key 與 Webhook signing secret。
SENTINEL_GEMINI_API_KEY=your-gemini-api-key
SENTINEL_RTSP_ALLOWED_HOSTS=10.40.8.21:554
SENTINEL_WEBHOOK_ALLOWED_HOSTS=partner-receiver:9090docker compose -f docker-compose.yml -f partner-webhook.compose.yml --profile ui up -d --build這會建置目前套件中的 API 與控制台，並在同一個 Docker 網路啟動接收器。 使用內網模型 · 部署選項
2. 在 Web GUI 設定攝影機與條件
- 在伺服器本機開啟 http://localhost:3000。API base URL 留白，填入 .env 的 SENTINEL_API_KEY，按 Connect and verify。遠端操作請使用 SSH tunnel 或受保護的反向代理。
- 到 Sources 新增 RTSP 攝影機，測試連線並確認預覽。
- 到 Monitors 選擇攝影機，填入要注意的條件，例如「有人進入管制區域時通知」，啟用並測試監看任務。先用現場代表性影像確認模型判斷符合需求。
3. 接收第一則 Webhook
到 Webhooks 新增端點，填入以下資料：
Name: Partner receiver
Destination URL: http://partner-receiver:9090/events
Signing secret environment variable: SENTINEL_WEBHOOK_SIGNING_SECRET
Enabled: on
Dry run: off
Severity: critical
State: raisedSigning secret 欄位填的是環境變數名稱，不是密鑰內容。第一次測試先不限制 event types、source IDs、monitor IDs。儲存後按 Test signed delivery，測試 severity 選 critical。
docker compose -f docker-compose.yml -f partner-webhook.compose.yml logs --tail=20 partner-receiver看到 accepted、evt_… 與 whd_… 代表接收器已驗證簽章並寫入 SQLite。再讓測試畫面符合監看條件，確認收到真正的異常事件。測試通知只驗證傳送路徑，不代表攝影機與模型已驗收完成。
怎麼接收？POST 推送與 GET 查詢
| 方式 | 誰呼叫誰 | 適合用途 |
|---|---|---|
| POST /events | Watch → 你的接收器 | 異常發生時，自動收到通知（建議） |
| GET /v1/events | 你的系統 → Watch | 主動查詢已保存事件 |
A. POST：在你的系統接收通知
你的後端要提供一個接受 POST 的網址，例如 /events。Watch 發現符合條件的事件後，會把上方 JSON 放在 request body 傳過來。下方流程與本頁下載的 Python 接收器一致：
# Inside the receiver's do_POST handler (shortened)
raw = self.rfile.read(length)
event = verify(raw, self.headers, secret)
fresh = accept(database, event, self.headers["X-Sentinel-Delivery-ID"], raw)
self.send_response(204)
self.end_headers()這段是處理流程節錄；完整原始碼包含 verify、accept、長度檢查與錯誤處理，可直接下載使用。verify 驗證 HMAC，accept 寫入 SQLite 並去重；儲存成功才回 204。業務程式再讀取 inbox，把事件顯示在你們的告警列表。
下載完整 POST 接收器（Python 3.11+，無額外套件）
如果已依上方 Compose 步驟啟動，接收器已在執行。不使用 Docker 時，在接收器主機設定與 Watch 相同的 signing secret，再啟動：
# Set these in the receiver's environment / secret manager:
# SENTINEL_WEBHOOK_SIGNING_SECRET = same secret as Watch
# RECEIVER_HOST = 0.0.0.0
# RECEIVER_PORT = 9090
python3 partner_webhook_receiver.py在 Watch 的 Webhooks 畫面填接收器 URL。Compose 範例是 http://partner-receiver:9090/events；正式遠端接收器使用你們的 HTTPS 網址。按 Test signed delivery 後，接收器日誌應出現 accepted；不需要把 Watch API key 放進接收網址。
B. GET：你的系統向 Watch 取事件
GET 由你們主動發出，Watch 回傳 JSON；不是 Watch 用 GET 推送通知。以下在 Watch 伺服器本機執行；遠端請把 base URL 換成受保護的 Watch HTTPS 位址。先在環境變數設定具有 events:read 權限的 SENTINEL_API_KEY。
# Query a page of stored events
curl --fail-with-body 'http://localhost:8000/v1/events?limit=10' \
-H "Authorization: Bearer $SENTINEL_API_KEY"回傳結構如下（data 裡每一筆都是上方的事件 JSON；此處以空列表示範）：
{
"object": "list",
"data": [],
"has_more": false,
"next_cursor": null
}has_more 為 true 時，把 next_cursor 原值放進 after 取得下一頁，不要自行組合 cursor。這是分頁查詢；最後一頁的 next_cursor 可能是 null，不能當作永久輪詢進度。持續即時通知使用上面的 Webhook。
# Set NEXT_CURSOR to the returned next_cursor value
curl --fail-with-body --get 'http://localhost:8000/v1/events' \
-H "Authorization: Bearer $SENTINEL_API_KEY" \
--data-urlencode "after=$NEXT_CURSOR" \
--data-urlencode 'limit=10'
# Set EVENT_ID to a real id from data[] or a webhook
curl --fail-with-body "http://localhost:8000/v1/events/$EVENT_ID" \
-H "Authorization: Bearer $SENTINEL_API_KEY"
# Download evidence when the event has an image
curl --fail "http://localhost:8000/v1/events/$EVENT_ID/image" \
-H "Authorization: Bearer $SENTINEL_API_KEY" \
--output event.jpg成功查詢回 200；401 請檢查 API key，403 請檢查 events:read 權限，404 請檢查事件 ID 或是否有圖片。POST 的 signing secret 與 GET 的 API key 是兩個不同用途的憑證。
接到你們自己的系統
範例只負責驗證、去重與保存事件。將 inbox 中的事件接到你們的告警列表或工作流程；依 type、severity、state 等結構化欄位處理，不要解析模型描述文字。Webhook 傳送警報與錯誤事件，不是每一筆普通推論。
正式接收端使用 HTTPS，與 Watch 共用簽章密鑰，驗證原始 request body，持久化成功後快速回覆 2xx。重送以 delivery ID 去重；同一 event 的不同 delivery 可能是狀態更新。SQLite 範例需另加業務處理、保留政策與容量規劃。