Terakhir diperbarui 2 Nov 2026

Webhook

Aturan peringatan dapat mengirim ke endpoint HTTPS, selain ke dalam aplikasi, email, dan Telegram. Setiap pengiriman adalah POST JSON yang ditandatangani dengan secret kanal, yang hanya ditampilkan sekali saat kanal dibuat.

Menyiapkan endpoint

Di dashboard, buka Alerts → Rules → New rule, pilih jenis event, lalu tambahkan kanal Webhook dengan URL HTTPS Anda. Dengan API key, kirim aturan yang sama ke POST /v1/alerts/rules (scope webhook:manage).
Salin signing secret (whsec_…). Secret ini dikembalikan sekali, di webhookSecrets[].signingSecret, satu per kanal webhook. Simpan bersama endpoint Anda.
Jawab dengan 2xx dalam 10 detik dan kerjakan prosesnya secara asinkron. Redirect tidak diikuti, dan alamat privat, loopback, atau link-local ditolak.
POST /v1/alerts/rules/{id}/test mengirim contoh pengiriman envelope (sourceEventId diawali test_) agar Anda dapat memeriksa handler Anda.

Event

Sebuah aturan mencantumkan jenis event yang ditanggapinya di eventTypes; daftar kosong cocok dengan semua jenis. Berikut jenis yang layak dijadikan peringatan:

Tipe	Terpicu saat
`envelope`	Sebuah amplop (treasure box) teramati di room yang dipantau. Nilai berlian minimum pada aturan berlaku.
`goodyBag`	Sebuah goody bag teramati di room yang dipantau. Nilai berlian minimum pada aturan berlaku.
`gift`	Sebuah hadiah dikirim di room yang dipantau. Terpicu pada setiap hadiah: nilai berlian minimum tidak berlaku.

minDiamondCount bernilai default 49 dan, bersama batas bawah 1.51 berlian per penonton, hanya menyaring amplop dan goody bag. Event mulai dan selesai LIVE belum dikirimkan.

Header

Header	Nilai
`content-type`	application/json
`x-roomscope-alert-id`	<ruleId>:<eventId>, nilai yang sama dengan alertId di body. Lakukan deduplikasi berdasarkan nilai ini.
`x-roomscope-timestamp`	Waktu Unix dalam detik saat percobaan ini ditandatangani.
`x-roomscope-schema-version`	Versi skema payload, saat ini 2026-11-03 (menambahkan `links`).
`x-roomscope-signature`	sha256=<hex HMAC-SHA256 dari "<timestamp>.<raw body>">.

Payload

Satu event per permintaan, dalam bentuk JSON ringkas. diamondCount, peopleCount, dan unpackAt (detik Unix) diisi untuk envelope dan goodyBag, dan bernilai null untuk tipe lainnya.

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"}

Memverifikasi tanda tangan

Tanda tangannya adalah HMAC-SHA256 dengan kunci berupa secret whsec_… lengkap, atas header timestamp, sebuah titik, dan raw body: <timestamp>.<body>. Digest hex dikirim sebagai sha256=<hex> di x-roomscope-signature. Bandingkan dalam waktu konstan, dan tolak timestamp di luar rentang waktu yang Anda pilih (lima menit pada contoh di bawah) untuk mencegah serangan 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);}

Gunakan raw body

Parse JSON hanya setelah tanda tangannya terverifikasi, dan hitung HMAC atas byte persis yang Anda terima. Menserialisasi ulang objek akan mengubah spasi dan escaping sehingga perbandingannya gagal.

Percobaan ulang dan kegagalan

Status di bawah 300 dianggap berhasil. 5xx, 408, 429, error jaringan, atau timeout akan dicoba ulang; 4xx lainnya atau 3xx adalah kegagalan permanen.
Sebuah pengiriman mendapat paling banyak 4 percobaan, dikirim berturut-turut tanpa jeda. Setiap percobaan ditandatangani ulang, sehingga deliveredAt, timestamp, dan tanda tangannya berubah. Lakukan deduplikasi berdasarkan alertId, bukan berdasarkan body.
Setelah pengiriman berhasil, alertId yang sama tidak dikirim lagi selama 7 hari.
Setiap webhook yang terkirim memakai 1 kredit. Sebuah workspace dapat menerima hingga 100,000 webhook per bulan kalender (UTC); pengiriman di atas jumlah itu dibuang.
Pengiriman yang gagal belum ditampilkan di dashboard. Catat permintaan yang Anda terima di log jika Anda memerlukan jejak audit.

Telegram dan email

Aturan yang sama juga dapat mengirim ke chat Telegram yang terhubung atau ke alamat email; kanal-kanal tersebut tidak memerlukan penanganan tanda tangan. Hubungkan Telegram dari Alerts → Channels.

Apakah halaman ini membantu?