Webhooks

إعداد نقطة نهاية

1. في لوحة التحكم افتح Alerts → Rules → New rule، واختر أنواع الأحداث، ثم أضف قناة Webhook مع عنوان HTTPS الخاص بك. وباستخدام مفتاح API، أرسل القاعدة نفسها إلى POST /v1/alerts/rules (النطاق webhook:manage).
2. انسخ سر التوقيع (whsec_…). يُرجَع مرة واحدة فقط، في webhookSecrets[].signingSecret، سرّ واحد لكل قناة webhook. احفظه مع نقطة النهاية الخاصة بك.
3. أجب برمز 2xx خلال 10 ثوانٍ، ونفّذ المعالجة بشكل غير متزامن. لا تُتبَع عمليات إعادة التوجيه، وتُرفض العناوين الخاصة وعناوين الاسترجاع (loopback) وعناوين الارتباط المحلي (link-local).
4. يرسل POST /v1/alerts/rules/{id}/test إرسالًا تجريبيًا من نوع envelope (تبدأ قيمة sourceEventId بـ test_) لتتحقق من معالجك.

الأحداث

تسرد القاعدة أنواع الأحداث التي تستجيب لها في eventTypes؛ والقائمة الفارغة تطابق كل الأنواع. هذه هي الأنواع التي تستحق التنبيه:

القيمة الافتراضية لـ minDiamondCount هي 49، وهي، مع حد أدنى قدره 1.51 ماسة لكل مشاهد، تُرشّح صناديق الكنز وحقائب الهدايا فقط. لا تُرسل أحداث بدء البث المباشر وانتهائه حتى الآن.

الترويسات

الحمولة

حدث واحد لكل طلب، بصيغة JSON مضغوطة. تُضبط الحقول diamondCount وpeopleCount وunpackAt (بثواني Unix) للنوعين 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_…، ويُحتسب على ترويسة الطابع الزمني، ثم نقطة، ثم جسم الطلب الخام: <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);}

إعادة المحاولة والإخفاقات

• أي حالة أقل من 300 تُعد نجاحًا. يُعاد إرسال الطلب عند 5xx أو 408 أو 429 أو خطأ في الشبكة أو انتهاء المهلة؛ أما أي 4xx آخر أو 3xx فيُعد إخفاقًا نهائيًا.
• يحصل الإرسال على 4 محاولات كحد أقصى، تُرسل واحدة تلو الأخرى دون تأخير. تُوقَّع كل محاولة من جديد، لذا تتغير قيمة deliveredAt والطابع الزمني والتوقيع. أزِل التكرار بالاعتماد على alertId، لا على جسم الطلب.
• بعد نجاح الإرسال، لا يُرسل alertId نفسه مرة أخرى لمدة 7 أيام.
• يكلّف كل webhook مُرسل وحدة رصيد واحدة. يمكن لمساحة العمل استقبال ما يصل إلى 100,000 webhook في الشهر الميلادي (بتوقيت UTC)؛ وتُسقَط الإرسالات التي تتجاوز ذلك.
• لا تُعرض الإرسالات الفاشلة في لوحة التحكم حتى الآن. سجّل الطلبات التي تستقبلها إن كنت بحاجة إلى سجل تدقيق.

Telegram والبريد الإلكتروني

يمكن للقاعدة نفسها أيضًا الإرسال إلى محادثة Telegram متصلة أو إلى عنوان بريد إلكتروني؛ ولا تتطلب هاتان القناتان أي معالجة للتوقيع. اربط Telegram من Alerts → Channels.