TikTok LIVE Webhooks

À quoi sert un webhook TikTok LIVE

Un webhook, c'est une alerte de passage en live livrée à ton serveur. On surveille les créateurs que tu listes et on envoie un POST HTTPS à ton URL quand l'un d'eux lance un LIVE (live.start), puis à nouveau quand le stream se termine (live.end). Ton service n'a pas besoin de garder une connexion ouverte ni de faire tourner un planificateur - il doit juste répondre à un POST.

Usages typiques : poster sur Discord ou Slack quand un créateur passe en live, lancer un enregistrement ou des analytics dès le début d'un stream, ouvrir une connexion WebSocket pour le chat et les cadeaux uniquement pendant que le créateur est vraiment en live, ou garder à jour le statut live du roster d'une agence.

Comment ça marche

1. Enregistre un webhook avec l'URL de ton endpoint, les événements voulus et les pseudos TikTok à surveiller.
2. Conserve le secret de signature, renvoyé une seule fois à la création. Chaque livraison est signée avec.
3. Reçois live.start et live.end sous forme de POST JSON. Vérifie la signature, réponds 200, puis fais ton traitement.

Événements

Enregistrer un webhook

Crée tes webhooks depuis le tableau de bord, ou de serveur à serveur avec ta clé API. La réponse contient le secret de signature, affiché une seule fois.

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.

Limite creators aux comptes qui t'intéressent (jusqu'à 1 000 par webhook). Pour modifier la liste plus tard, fais un PATCH du webhook avec le nouveau tableau complet - il remplace la liste précédente. Tous les paramètres sont dans la référence de l'API.

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

Chaque livraison porte aussi les en-têtes X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt et X-Tiktool-Webhook-Id.

Vérifier la signature

Chaque POST inclut X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, où v1 est le HMAC-SHA256 de "<t>.<raw body>" avec le secret de ton webhook comme clé. Calcule-le sur le corps brut avant de parser le JSON, compare en temps constant et rejette les timestamps de plus de cinq minutes.

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)

Livraison et relances

• Au moins une fois. Le même événement peut arriver plusieurs fois, donc dédoublonne sur event_id.
• Relances. Une livraison échouée est relancée selon le calendrier 0s, 30s, 2m, 10m, 1h et 6h. Après la dernière tentative, elle est conservée en dead letter que tu peux rejouer depuis le tableau de bord ou l'API une fois ton endpoint rétabli.
• Réponds vite. Renvoie un 2xx dès l'arrivée du POST et traite ensuite. Le délai de connexion est de 10 secondes et le délai de lecture de 15 secondes ; une connexion refusée ou un délai dépassé compte comme une tentative échouée.
• Teste quand tu veux. Envoie une livraison de test signée à ton endpoint depuis le tableau de bord ou l'endpoint de test pour vérifier le parsing et la gestion de la signature avant qu'un créateur passe en live.

Offres

Les webhooks avec live.start et live.end sont inclus dans toutes les offres payantes, avec plus d'endpoints et un quota de livraisons quotidien plus élevé sur les offres supérieures. Un compte Sandbox peut configurer un webhook de test depuis le tableau de bord et lui envoyer des livraisons de test signées, pour construire l'intégration avant de t'abonner. Les livraisons réelles et l'enregistrement de webhooks avec une clé API nécessitent une offre payante. Consulte les tarifs pour le détail des offres.

Questions fréquentes