TikTok LIVE Webhook'ları

TikTok LIVE webhook'u ne yapar

Webhook, sunucuna iletilen bir yayın başladı bildirimidir. Listelediğin yayıncıları izleriz; biri LIVE başlattığında (live.start) ve yayın bittiğinde (live.end) URL'ne bir HTTPS POST göndeririz. Hizmetinin bir bağlantıyı açık tutmasına ya da zamanlayıcı çalıştırmasına gerek yok; sadece bir POST'a yanıt vermesi yeterli.

Tipik kullanımlar: bir yayıncı canlıya geçtiğinde Discord ya da Slack'e paylaşım yapmak, yayın başladığı anda kayda ya da analize başlamak, sohbet ve hediyeler için yalnızca yayıncı gerçekten canlıdayken bir WebSocket bağlantısı açmak ya da bir ajans kadrosunun canlı durumunu güncel tutmak.

Nasıl çalışır

1. Uç nokta URL'n, istediğin olaylar ve izlenecek TikTok kullanıcı adlarıyla bir webhook kaydet.
2. İmzalama anahtarını sakla; oluşturma sırasında yalnızca bir kez döndürülür. Her gönderim bununla imzalanır.
3. live.start ve live.end olaylarını al: JSON POST olarak gelir. İmzayı doğrula, 200 ile yanıt ver, sonra işini yap.

Olaylar

Bir webhook kaydet

Webhook'ları panelden ya da API anahtarınla sunucudan sunucuya oluştur. Yanıt, yalnızca bir kez gösterilen imzalama anahtarını içerir.

curl -X POST "https://api.tik.tools/webcast/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Go-live alerts",
    "target_url": "https://your-app.com/hooks/tiktok-live",
    "event_types": ["live.start", "live.end"],
    "creators": ["creator_one", "creator_two"]
  }'

# The response carries webhook.id and the signing secret.
# The secret is returned once - store it with your config.

creators listesini önem verdiğin hesaplarla sınırlı tut (webhook başına en fazla 1.000). Listeyi sonradan değiştirmek için webhook'u yeni dizinin tamamıyla PATCH et; önceki listenin yerini alır. Tüm parametreler API referansı içinde.

Yükler

live.start

{
  "event_id": "evt_01J...",
  "event": "live.start",
  "occurred_at": "2026-06-18T13:00:00.000Z",
  "is_test": false,
  "creator": {
    "unique_id": "creator_one",
    "nickname": "Creator One",
    "avatar_url": "https://...",
    "user_id": "6569595380449902593",
    "follower_count": 1250000
  },
  "live": {
    "room_id": "7000000000000000000",
    "started_at": "2026-06-18T13:00:00.000Z",
    "live_url": "https://www.tiktok.com/@creator_one/live"
  }
}

live.end

{
  "event_id": "evt_01J...",
  "event": "live.end",
  "occurred_at": "2026-06-18T14:30:00.000Z",
  "is_test": false,
  "creator": { "unique_id": "creator_one", "nickname": "Creator One" },
  "live": { "room_id": "7000000000000000000", "ended_at": "2026-06-18T14:30:00.000Z" }
}

Her gönderim ayrıca X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt ve X-Tiktool-Webhook-Id başlıklarını taşır.

İmzayı doğrula

Her POST X-Tiktool-Signature: t=<unix_ts>,v1=<hex> içerir; burada v1, webhook anahtarınla anahtarlanmış "<t>.<raw body>" değerinin HMAC-SHA256'sıdır. JSON'u ayrıştırmadan önce ham gövde üzerinden hesapla, sabit sürede karşılaştır ve beş dakikadan eski zaman damgalarını reddet.

Node.js

import crypto from 'node:crypto'

export function verifyTiktoolWebhook(rawBody, header, secret) {
  const t = Number(header.match(/t=(\d+)/)?.[1])
  const v1 = header.match(/v1=([a-f0-9]+)/)?.[1]
  if (!t || !v1) return false
  if (Math.abs(Date.now() / 1000 - t) > 300) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return expected.length === v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}

Python

import hashlib, hmac, time

def verify_tiktool_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1 or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Gönderim ve yeniden denemeler

• En az bir kez. Aynı olay birden fazla kez gelebilir, bu yüzden event_id ile tekilleştir.
• Yeniden denemeler. Başarısız bir gönderim 0 sn, 30 sn, 2 dk, 10 dk, 1 sa ve 6 sa aralıklarıyla yeniden denenir. Son denemeden sonra, uç noktan düzelince panelden ya da API'den tekrar gönderebileceğin bir teslim edilemeyen kayıt olarak saklanır.
• Hızlı yanıt ver. POST gelir gelmez bir 2xx döndür, işlemi sonra yap. Bağlantı zaman aşımı 10 saniye, okuma zaman aşımı 15 saniye; reddedilen bir bağlantı ya da zaman aşımı başarısız deneme sayılır.
• İstediğin zaman test et. Bir yayıncı canlıya geçmeden önce ayrıştırmayı ve imza kontrolünü denemek için panelden ya da test uç noktasından uç noktana imzalı bir test gönderimi yap.

Planlar

live.start ve live.end webhook'ları tüm ücretli planlara dahil; üst planlarda daha fazla uç nokta ve daha yüksek günlük gönderim kotası var. Sandbox hesabı panelden bir test webhook'u kurup ona imzalı test gönderimleri yapabilir, böylece entegrasyonu abone olmadan önce geliştirebilirsin. Canlı gönderimler ve API anahtarıyla webhook kaydı ücretli plan gerektirir. Plan ayrıntıları için fiyatlar sayfasına bak.

Sıkça Sorulan Sorular