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
- 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(scopewebhook:manage). - Sao chép signing secret (
whsec_…). Nó chỉ được trả về một lần, trongwebhookSecrets[].signingSecret, mỗi kênh webhook một secret. Hãy lưu nó cùng endpoint của bạn. - Trả lời bằng
2xxtrong 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. POST /v1/alerts/rules/{id}/testgửi một lần gửi mẫuenvelope(sourceEventIdbắt đầu bằngtest_) để 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ại | Kích hoạt khi |
|---|---|
envelope | Ghi 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. |
goodyBag | Ghi 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. |
gift | Có 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
| Header | Giá trị |
|---|---|
content-type | application/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-timestamp | Unix time tính bằng giây tại thời điểm lần gửi này được ký. |
x-roomscope-schema-version | Phiên bản schema của payload, hiện là 2026-11-03 (thêm `links`). |
x-roomscope-signature | sha256=<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.
{ "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);}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ọi4xxkhác hoặc3xxlà 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 theoalertId, không theo body. - Sau một lần gửi thành công, cùng
alertIdsẽ 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.