RoomScope

Cập nhật lần cuối

Webhook

Một luật cảnh báo có thể gửi tới một endpoint HTTPS, bên cạnh trong app, email và Telegram. Mỗi lần gửi là một POST JSON được ký bằng secret của kênh, secret này chỉ hiện một lần khi kênh được tạo.

Thiết lập endpoint

  1. Trong dashboard, mở Cảnh báo → Luật → Luật mới, chọn các loại sự kiện và thêm một kênh Webhook với URL HTTPS của bạn. Với API key, gửi cùng luật đó tới POST /v1/alerts/rules (scope webhook:manage).
  2. Sao chép signing secret (whsec_…). Nó chỉ được trả về một lần, trong webhookSecrets[].signingSecret, mỗi kênh webhook một secret. Hãy lưu nó cùng endpoint của bạn.
  3. Trả lời bằng 2xx trong vòng 10 giây và xử lý công việc bất đồng bộ. Redirect không được theo, và các địa chỉ private, loopback hoặc link-local đều bị từ chối.
  4. POST /v1/alerts/rules/{id}/test gửi một lần gửi mẫu envelope (sourceEventId bắt đầu bằng test_) để bạn kiểm tra handler của mình.

Sự kiện

Một luật liệt kê các loại sự kiện nó phản ứng trong eventTypes; danh sách rỗng khớp với mọi loại. Đây là các loại đáng để cảnh báo:

LoạiKích hoạt khi
envelopeGhi nhận một bao lì xì trong một phòng được theo dõi. Áp dụng giá trị kim cương tối thiểu của luật.
goodyBagGhi nhận một goody bag trong một phòng được theo dõi. Áp dụng giá trị kim cương tối thiểu của luật.
giftCó quà được tặng trong một phòng được theo dõi. Kích hoạt với mọi món quà: không áp dụng giá trị kim cương tối thiểu.

minDiamondCount mặc định là 49 và, cùng với mức sàn 1.51 kim cương mỗi người xem, chỉ dùng để lọc bao lì xì và goody bag. Sự kiện bắt đầu và kết thúc LIVE hiện chưa được gửi.

Header

HeaderGiá trị
content-typeapplication/json
x-roomscope-alert-id<ruleId>:<eventId>, cùng giá trị với alertId trong body. Dùng nó để loại trùng.
x-roomscope-timestampUnix time tính bằng giây tại thời điểm lần gửi này được ký.
x-roomscope-schema-versionPhiên bản schema của payload, hiện là 2026-11-03 (thêm `links`).
x-roomscope-signaturesha256=<hex HMAC-SHA256 của "<timestamp>.<raw body>">.

Payload

Mỗi request một sự kiện, dưới dạng JSON thu gọn. diamondCount, peopleCount và unpackAt (Unix seconds) có giá trị với envelope và goodyBag, và là null với các loại khác.

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.next.toktokdata.live/creators/room.one",    "session": "https://app.next.toktokdata.live/live?creator=room.one"  },  "occurredAt": "2026-11-01T10:02:31.123Z",  "deliveredAt": "2026-11-01T10:02:33.456Z"}

Xác minh chữ ký

Chữ ký là HMAC-SHA256, dùng khóa là toàn bộ secret whsec_…, tính trên header timestamp, một dấu chấm và body thô: <timestamp>.<body>. Bản băm dạng hex được gửi dưới dạng sha256=<hex> trong x-roomscope-signature. Hãy so sánh trong thời gian hằng định, và từ chối các timestamp nằm ngoài khoảng bạn chọn (năm phút trong ví dụ dưới đây) để chặn tấn công phát lại.

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);}
Dùng body thô
Chỉ parse JSON sau khi chữ ký đã hợp lệ, và tính HMAC trên đúng các byte bạn nhận được. Serialize lại object sẽ thay đổi khoảng trắng và ký tự escape, làm phép so sánh sai.

Thử lại và thất bại

  • Status dưới 300 là thành công. 5xx, 408, 429, lỗi mạng hoặc timeout sẽ được thử lại; mọi 4xx khác hoặc 3xx là thất bại vĩnh viễn.
  • Mỗi lần gửi có tối đa 4 lần thử, gửi liên tiếp nhau không có độ trễ. Mỗi lần thử được ký lại, nên deliveredAt, timestamp và chữ ký sẽ thay đổi. Hãy loại trùng theo alertId, không theo body.
  • Sau một lần gửi thành công, cùng alertId sẽ không được gửi lại trong 7 ngày.
  • Mỗi webhook đã gửi tốn 1 credit. Một workspace nhận được tối đa 100,000 webhook mỗi tháng dương lịch (UTC); các lần gửi vượt quá sẽ bị bỏ.
  • Các lần gửi thất bại hiện chưa được liệt kê trong dashboard. Hãy ghi log các request bạn nhận nếu cần lưu vết kiểm tra.

Telegram và email

Cùng một luật cũng có thể gửi tới một chat Telegram đã kết nối hoặc một địa chỉ email; các kênh này không cần xử lý chữ ký. Kết nối Telegram tại Cảnh báo → Kênh.

Trang này có hữu ích không?