RoomScope

最後更新

Webhook

除了應用程式內、電子郵件與 Telegram 之外，提醒規則也可以推送到 HTTPS 端點。每次推送都是以通道密鑰簽章的 JSON POST 請求；該密鑰只會在建立通道時顯示一次。

設定端點

  1. 在主控台開啟 提醒 → 規則 → 新增規則，選擇事件類型，並以你的 HTTPS 網址新增一個 Webhook 通道。若使用 API 金鑰，請將相同的規則送到 POST /v1/alerts/rules（權限範圍 webhook:manage）。
  2. 複製簽章密鑰（whsec_…）。它只會在 webhookSecrets[].signingSecret 中回傳一次，每個 Webhook 通道各一組。請將它與你的端點一起保存。
  3. 請在 10 秒內回應 2xx，並以非同步方式處理後續工作。系統不會跟隨重新導向，也會拒絕私有、迴路或鏈路本地位址。
  4. POST /v1/alerts/rules/{id}/test 會送出一筆範例 envelope 推送（sourceEventId 以 test_ 開頭），方便你檢查處理程式。

事件

規則會在 eventTypes 中列出它要回應的事件類型；空清單代表符合所有類型。以下是值得設定提醒的類型：

類型觸發時機
envelope在觀察中的直播間觀測到寶箱（紅包）。適用規則設定的最低鑽石值。
goodyBag在觀察中的直播間觀測到福袋。適用規則設定的最低鑽石值。
gift在觀察中的直播間有人送出禮物。每份禮物都會觸發：不適用最低鑽石值。

minDiamondCount 預設為 49，並與每位觀眾 1.51 顆鑽石的下限一起，只用於篩選寶箱與福袋。開播與結束直播事件目前尚未推送。

標頭

標頭值
content-typeapplication/json
x-roomscope-alert-id<ruleId>:<eventId>，與請求主體中的 alertId 相同。請以此值去除重複。
x-roomscope-timestamp此次嘗試簽章時的 Unix 時間（秒）。
x-roomscope-schema-versionPayload 結構描述版本，目前為 2026-11-03（新增 `links`）。
x-roomscope-signaturesha256=<"<timestamp>.<raw body>" 的十六進位 HMAC-SHA256>。

Payload

每個請求一個事件，以精簡的 JSON 傳送。diamondCount、peopleCount 與 unpackAt（Unix 秒）只在 envelope 與 goodyBag 時有值，其他類型則為 null。

POST your-endpoint
{  "schemaVersion": "2026-11-03",  "alertId": "8f0c…:evt_…",  "rule": { "id": "8f0c…", "name": "Big treasure boxes" },  "event": {    "type": "envelope",    "sourceEventId": "evt_…",    "roomId": "7432…",    "creatorUniqueId": "room.one",    "region": "VN",    "diamondCount": 5000,    "peopleCount": 120,    "score": 5000,    "unpackAt": 1793520000,    "observedAt": "2026-11-01T10:02:31.123Z"  },  "links": {    "creator": "https://app.toktokdata.live/creators/room.one",    "session": "https://app.toktokdata.live/live?creator=room.one"  },  "occurredAt": "2026-11-01T10:02:31.123Z",  "deliveredAt": "2026-11-01T10:02:33.456Z"}

驗證簽章

簽章為 HMAC-SHA256，以完整的 whsec_… 密鑰為金鑰，計算對象是時間戳記標頭、一個句點與原始請求主體：<timestamp>.<body>。十六進位摘要會以 sha256=<hex> 的格式放在 x-roomscope-signature 中送出。請以固定時間演算法比對，並拒絕超出你所設定時間範圍（以下範例為五分鐘）的時間戳記，以防止重送攻擊。

import { createHmac, timingSafeEqual } from "node:crypto"; // rawBody: the exact bytes received, e.g. express.raw({ type: "application/json" }).// secret: the full whsec_… value shown when the webhook channel was created.export function verify(rawBody, headers, secret, toleranceSec = 300) {  const signature = headers["x-roomscope-signature"];  const timestamp = headers["x-roomscope-timestamp"];  if (!signature || !/^\d+$/.test(timestamp ?? "")) return false;  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;  const expected =    "sha256=" + createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");  const a = Buffer.from(signature, "utf8");  const b = Buffer.from(expected, "utf8");  return a.length === b.length && timingSafeEqual(a, b);}
使用原始請求主體
請在簽章驗證通過後才解析 JSON，並以你收到的原始位元組計算 HMAC。重新序列化物件會改變空白與跳脫字元，導致比對失敗。

重試與失敗

  • 狀態碼低於 300 即視為成功。5xx、408、429、網路錯誤或逾時會重試；其他 4xx 或 3xx 則視為永久失敗。
  • 每次推送最多嘗試 4 次，一次接著一次送出，中間沒有延遲。每次嘗試都會重新簽章，因此 deliveredAt、時間戳記與簽章都會改變。請以 alertId 去除重複，而不是以請求主體判斷。
  • 推送成功後，同一個 alertId 在 7 天內不會再次推送。
  • 每個成功推送的 Webhook 花費 1 點。每個工作區每個日曆月（UTC）最多可接收 100,000 個 Webhook；超過的推送會被捨棄。
  • 主控台目前尚未列出推送失敗的紀錄。若需要稽核軌跡，請自行記錄你收到的請求。

Telegram 與電子郵件

同一條規則也可以推送到已連結的 Telegram 聊天室或電子郵件地址；這些通道不需要處理簽章。請在 提醒 → 通道 中連結 Telegram。

這個頁面對你有幫助嗎？