Son güncelleme 2 Kas 2026

Webhook’lar

Bir uyarı kuralı; uygulama içi, e-posta ve Telegram’ın yanı sıra bir HTTPS endpoint’ine de teslimat yapabilir. Her teslimat, kanalın gizli anahtarıyla imzalanmış bir JSON POST isteğidir; bu gizli anahtar kanal oluşturulduğunda yalnızca bir kez gösterilir.

Bir endpoint kurma

Panelde Uyarılar → Kurallar → Yeni kural yolunu açın, olay türlerini seçin ve HTTPS URL’nizle bir Webhook kanalı ekleyin. Bir API anahtarıyla aynı kuralı POST /v1/alerts/rules adresine gönderin (kapsam webhook:manage).
İmzalama gizli anahtarını (whsec_…) kopyalayın. Her webhook kanalı için bir tane olmak üzere, webhookSecrets[].signingSecret içinde yalnızca bir kez döndürülür. Onu endpoint’inizle birlikte saklayın.
10 saniye içinde bir 2xx ile yanıt verin ve işi asenkron olarak yapın. Yönlendirmeler izlenmez; özel, loopback veya link-local adresler reddedilir.
POST /v1/alerts/rules/{id}/test, işleyicinizi kontrol edebilmeniz için örnek bir envelope teslimatı gönderir (sourceEventId değeri test_ ile başlar).

Olaylar

Bir kural, tepki verdiği olay türlerini eventTypes içinde listeler; boş bir liste her türle eşleşir. Uyarı kurmaya değer türler şunlardır:

Tür	Ne zaman tetiklenir
`envelope`	İzlenen bir odada bir zarf (hazine kutusu) gözlemlendi. Kuralın minimum elmas değeri uygulanır.
`goodyBag`	İzlenen bir odada bir goody bag gözlemlendi. Kuralın minimum elmas değeri uygulanır.
`gift`	İzlenen bir odada bir hediye gönderildi. Her hediyede tetiklenir: minimum elmas değeri uygulanmaz.

minDiamondCount varsayılan olarak 49’dur ve izleyici başına 1.51 elmaslık bir alt sınırla birlikte yalnızca zarfları ve goody bag’leri filtreler. LIVE başlangıç ve bitiş olayları henüz teslim edilmiyor.

Başlıklar

Başlık	Değer
`content-type`	application/json
`x-roomscope-alert-id`	<ruleId>:<eventId>; gövdedeki alertId ile aynı değer. Tekilleştirmeyi buna göre yapın.
`x-roomscope-timestamp`	Bu denemenin imzalandığı an, saniye cinsinden Unix zamanı.
`x-roomscope-schema-version`	Payload şema sürümü; şu anda 2026-11-03 (`links` alanını ekler).
`x-roomscope-signature`	sha256=<"<timestamp>.<raw body>" üzerinden hesaplanan hex HMAC-SHA256>.

Payload

İstek başına bir olay, sıkıştırılmış JSON olarak. diamondCount, peopleCount ve unpackAt (Unix saniyesi) envelope ve goodyBag için doldurulur, diğer türlerde null olur.

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

İmzaları doğrulama

İmza, tam whsec_… gizli anahtarıyla anahtarlanmış bir HMAC-SHA256’dır; zaman damgası başlığı, bir nokta ve ham gövde üzerinden hesaplanır: <timestamp>.<body>. Hex özet, x-roomscope-signature içinde sha256=<hex> olarak gönderilir. Karşılaştırmayı sabit zamanlı yapın ve tekrar saldırılarını önlemek için seçtiğiniz bir pencerenin (aşağıda beş dakika) dışındaki zaman damgalarını reddedin.

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

Ham gövdeyi kullanın

JSON’u yalnızca imza doğrulandıktan sonra ayrıştırın ve HMAC’i tam olarak aldığınız baytlar üzerinden hesaplayın. Nesneyi yeniden serileştirmek boşlukları ve kaçış karakterlerini değiştirir ve karşılaştırmayı bozar.

Yeniden denemeler ve hatalar

300’ün altındaki bir durum başarıdır. Bir 5xx, 408, 429, ağ hatası veya zaman aşımı yeniden denenir; diğer tüm 4xx yanıtları veya bir 3xx kalıcı başarısızlıktır.
Bir teslimat en fazla 4 deneme alır; denemeler beklemeden art arda gönderilir. Her deneme yeniden imzalanır, bu yüzden deliveredAt, zaman damgası ve imza değişir. Tekilleştirmeyi gövdeye göre değil, alertId değerine göre yapın.
Başarılı bir teslimattan sonra aynı alertId 7 gün boyunca yeniden teslim edilmez.
Teslim edilen her webhook 1 kredi tutar. Bir çalışma alanı takvim ayı (UTC) başına en fazla 100,000 webhook alabilir; bunun üzerindeki teslimatlar atılır.
Başarısız teslimatlar henüz panelde listelenmiyor. Bir denetim kaydına ihtiyacınız varsa aldığınız istekleri günlüğe yazın.

Telegram ve e-posta

Aynı kural, bağlı bir Telegram sohbetine veya bir e-posta adresine de teslimat yapabilir; bu kanallar imza işlemi gerektirmez. Telegram’ı Uyarılar → Kanallar bölümünden bağlayın.

Bu sayfa işinize yaradı mı?