TikTok LIVE Webhooks

Was ein TikTok LIVE Webhook macht

Ein Webhook ist ein Live-Alert, der an deinen Server geht. Wir beobachten die Creator auf deiner Liste und schicken einen HTTPS-POST an deine URL, wenn einer von ihnen ein LIVE startet (live.start) und noch einmal, wenn der Stream endet (live.end). Dein Dienst muss keine Verbindung offen halten und keinen Scheduler laufen lassen - er muss nur auf einen POST antworten.

Typische Einsätze: in Discord oder Slack posten, wenn ein Creator live geht, Aufnahme oder Analytics in dem Moment starten, in dem ein Stream beginnt, eine WebSocket-Verbindung für Chat und Geschenke nur öffnen, solange der Creator wirklich live ist, oder den Live-Status eines Agentur-Rosters aktuell halten.

So funktioniert's

1. Registrier einen Webhook mit deiner Endpunkt-URL, den gewünschten Events und den TikTok-Usernamen, die beobachtet werden sollen.
2. Speicher das Signing-Secret, das beim Erstellen einmalig zurückkommt. Jede Zustellung wird damit signiert.
3. Empfang live.start und live.end als JSON-POSTs. Prüf die Signatur, antworte mit 200 und erledige dann deine Arbeit.

Events

Webhook registrieren

Erstell Webhooks im Dashboard oder Server-zu-Server mit deinem API-Key. Die Antwort enthält das Signing-Secret, das nur einmal angezeigt wird.

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.

Beschränk creators auf die Accounts, die dich interessieren (bis zu 1.000 pro Webhook). Um die Liste später zu ändern, schick ein PATCH an den Webhook mit dem kompletten neuen Array - es ersetzt die bisherige Liste. Alle Parameter findest du in der API-Referenz.

Payloads

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

Jede Zustellung enthält außerdem die Header X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt und X-Tiktool-Webhook-Id.

Signatur prüfen

Jeder POST enthält X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, wobei v1 der HMAC-SHA256 von "<t>.<raw body>" ist, mit deinem Webhook-Secret als Schlüssel. Berechne ihn über den Raw-Body, bevor du das JSON parst, vergleich in konstanter Zeit und lehn Zeitstempel ab, die älter als fünf Minuten sind.

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)

Zustellung und Wiederholungen

• Mindestens einmal. Dasselbe Event kann mehr als einmal ankommen, also dedupliziere anhand von event_id.
• Wiederholungen. Eine fehlgeschlagene Zustellung wird nach dem Schema 0 s, 30 s, 2 min, 10 min, 1 h und 6 h wiederholt. Nach dem letzten Versuch wird sie als Dead Letter aufbewahrt, den du im Dashboard oder per API erneut senden kannst, sobald dein Endpunkt wieder läuft.
• Antworte schnell. Gib einen 2xx zurück, sobald der POST ankommt, und verarbeite erst danach. Das Verbindungs-Timeout liegt bei 10 Sekunden, das Lese-Timeout bei 15 Sekunden; eine abgelehnte Verbindung oder ein Timeout zählt als fehlgeschlagener Versuch.
• Jederzeit testen. Schick im Dashboard oder über den Test-Endpunkt eine signierte Testzustellung an deinen Endpunkt, um Parsing und Signaturprüfung zu checken, bevor ein Creator live geht.

Tarife

Webhooks mit live.start und live.end sind in jedem bezahlten Tarif enthalten, höhere Tarife bieten mehr Endpunkte und ein größeres tägliches Zustellungskontingent. Mit einem Sandbox-Konto kannst du im Dashboard einen Test-Webhook einrichten und signierte Testzustellungen daran schicken, damit die Integration schon vor dem Abo fertig ist. Echte Zustellungen und das Registrieren von Webhooks per API-Key brauchen einen bezahlten Tarif. Details zu den Tarifen findest du unter Preise.

Häufige Fragen