Webhook

การตั้งค่า endpoint

1. ในแดชบอร์ด เปิด Alerts → Rules → New rule เลือกประเภทอีเวนต์ แล้วเพิ่มช่องทาง Webhook พร้อม HTTPS URL ของคุณ หากใช้ API key ให้ส่งกฎเดียวกันไปที่ POST /v1/alerts/rules (สโคป webhook:manage)
2. คัดลอก คีย์ลับสำหรับลงลายเซ็น (whsec_…) ซึ่งส่งกลับมาเพียงครั้งเดียวใน webhookSecrets[].signingSecret หนึ่งค่าต่อหนึ่งช่องทาง webhook เก็บไว้คู่กับ endpoint ของคุณ
3. ตอบกลับด้วย 2xx ภายใน 10 วินาที แล้วประมวลผลงานแบบอะซิงโครนัส ระบบจะไม่ตาม redirect และจะปฏิเสธที่อยู่แบบ private, loopback หรือ link-local
4. POST /v1/alerts/rules/{id}/test จะส่งตัวอย่างการส่ง envelope (sourceEventId ขึ้นต้นด้วย test_) เพื่อให้คุณตรวจสอบตัวจัดการของคุณได้

อีเวนต์

กฎจะระบุประเภทอีเวนต์ที่ตอบสนองไว้ใน eventTypes หากเป็นรายการว่างจะตรงกับทุกประเภท ประเภทที่ควรตั้งการแจ้งเตือนมีดังนี้

minDiamondCount มีค่าเริ่มต้นเป็น 49 และเมื่อใช้ร่วมกับเกณฑ์ขั้นต่ำ 1.51 เพชรต่อผู้ชมหนึ่งคน จะกรองเฉพาะซองอั่งเปาและถุงของขวัญเท่านั้น ขณะนี้ยังไม่มีการส่งอีเวนต์เริ่มและสิ้นสุด LIVE

Header

Payload

หนึ่งอีเวนต์ต่อหนึ่งคำขอ ในรูปแบบ JSON แบบกระชับ diamondCount, peopleCount และ unpackAt (Unix seconds) จะมีค่าสำหรับ envelope และ goodyBag และเป็น null สำหรับประเภทอื่น

{  "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_… แบบเต็ม คำนวณจาก header timestamp จุด และ body ดิบ: <timestamp>.<body> ค่า hex digest จะถูกส่งในรูปแบบ sha256=<hex> ใน x-roomscope-signatureให้เปรียบเทียบแบบ constant time และปฏิเสธ timestamp ที่อยู่นอกช่วงเวลาที่คุณกำหนด (ตัวอย่างด้านล่างใช้ห้านาที) เพื่อป้องกันการโจมตีแบบ replay

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);}

การลองส่งใหม่และความล้มเหลว

• สถานะต่ำกว่า 300 ถือว่าสำเร็จ 5xx, 408, 429 ข้อผิดพลาดเครือข่าย หรือการหมดเวลาจะถูกลองส่งใหม่ ส่วน 4xx อื่น ๆ หรือ 3xx ถือเป็นความล้มเหลวถาวร
• การส่งแต่ละครั้งพยายามได้สูงสุด 4 ครั้ง ส่งต่อเนื่องกันโดยไม่มีการหน่วงเวลา แต่ละครั้งจะลงลายเซ็นใหม่ ดังนั้น deliveredAt, timestamp และลายเซ็นจะเปลี่ยนไป ให้กรองรายการซ้ำด้วย alertId ไม่ใช่ด้วย body
• หลังจากส่งสำเร็จ alertId เดิมจะไม่ถูกส่งซ้ำอีกเป็นเวลา 7 วัน
• webhook แต่ละรายการที่ส่งสำเร็จใช้ 1 เครดิต เวิร์กสเปซหนึ่งรับ webhook ได้สูงสุด 100,000 รายการต่อเดือนปฏิทิน (UTC) การส่งที่เกินจากนั้นจะถูกทิ้ง
• ขณะนี้แดชบอร์ดยังไม่แสดงรายการการส่งที่ล้มเหลว หากต้องการบันทึกสำหรับการตรวจสอบ ให้บันทึก log ของคำขอที่คุณได้รับไว้เอง

Telegram และอีเมล

กฎเดียวกันยังส่งไปยังแชต Telegram ที่เชื่อมต่อไว้หรือที่อยู่อีเมลได้ ช่องทางเหล่านั้นไม่ต้องจัดการลายเซ็น เชื่อมต่อ Telegram ได้จาก Alerts → Channels