TikTok LIVE Webhook-uri

Ce face un webhook TikTok LIVE

Un webhook este o alertă de intrare LIVE livrată serverului tău. Urmărim creatorii din lista ta și trimitem un POST HTTPS la URL-ul tău când unul dintre ei începe un LIVE (live.start) și din nou când LIVE-ul se încheie (live.end). Serviciul tău nu trebuie să țină o conexiune deschisă sau să ruleze un planificator - trebuie doar să răspundă la un POST.

Utilizări tipice: postezi pe Discord sau Slack când un creator intră LIVE, pornești înregistrarea sau analiza în momentul în care începe LIVE-ul, deschizi o conexiune WebSocket pentru chat și cadouri doar cât timp creatorul chiar este LIVE sau ții la zi starea LIVE a portofoliului de creatori al agenției.

Cum funcționează

1. Înregistrează un webhook cu URL-ul endpoint-ului, evenimentele dorite și numele de utilizator TikTok de urmărit.
2. Păstrează secretul de semnare returnat o singură dată la creare. Fiecare livrare este semnată cu el.
3. Primește live.start și live.end ca POST-uri JSON. Verifică semnătura, răspunde cu 200, apoi fă-ți treaba.

Evenimente

Înregistrează un webhook

Creează webhook-uri din panoul de control sau server-la-server cu cheia ta API. Răspunsul include secretul de semnare, afișat o singură dată.

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.

Limitează creators la conturile care te interesează (până la 1.000 per webhook). Ca să schimbi lista mai târziu, fă PATCH pe webhook cu întregul array nou - acesta înlocuiește lista anterioară. Toți parametrii sunt în referința API.

Payload-uri

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

Fiecare livrare conține și header-ele X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt și X-Tiktool-Webhook-Id.

Verifică semnătura

Fiecare POST include X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, unde v1 este HMAC-SHA256 al "<t>.<raw body>", cu cheia secretului webhook-ului tău. Calculează-l pe corpul brut înainte de a parsa JSON-ul, compară în timp constant și respinge timestamp-urile mai vechi de cinci minute.

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)

Livrare și reîncercări

• Cel puțin o dată. Același eveniment poate sosi de mai multe ori, așa că elimină duplicatele după event_id.
• Reîncercări. O livrare eșuată este reîncercată după programul 0 s, 30 s, 2 min, 10 min, 1 h și 6 h. După ultima încercare, este păstrată ca livrare eșuată (dead letter) pe care o poți retrimite din panoul de control sau din API după ce endpoint-ul tău funcționează din nou.
• Răspunde rapid. Returnează un 2xx imediat ce sosește POST-ul și procesează după aceea. Timeout-ul de conectare este de 10 secunde, iar cel de citire de 15 secunde; o conexiune refuzată sau un timeout contează ca încercare eșuată.
• Testează oricând. Trimite o livrare de test semnată către endpoint-ul tău din panoul de control sau prin endpoint-ul de test, ca să verifici parsarea și semnătura înainte ca un creator să intre LIVE.

Planuri

Webhook-urile cu live.start și live.end sunt incluse în fiecare plan plătit, cu mai multe endpoint-uri și o limită zilnică de livrări mai mare pe planurile superioare. Un cont Sandbox poate configura un webhook de test din panoul de control și îi poate trimite livrări de test semnate, ca integrarea să fie gata înainte să te abonezi. Livrările reale și înregistrarea webhook-urilor cu cheie API necesită un plan plătit. Vezi prețurile pentru detaliile planurilor.

Întrebări frecvente