TikTok LIVE Webhook

Cosa fa un webhook di TikTok LIVE

Un webhook è un avviso di inizio diretta consegnato al tuo server. Seguiamo i creator che indichi e inviamo una POST HTTPS al tuo URL quando uno di loro inizia una LIVE (live.start) e di nuovo quando la diretta finisce (live.end). Il tuo servizio non deve tenere aperta una connessione né far girare uno scheduler: deve solo rispondere a una POST.

Usi tipici: pubblicare su Discord o Slack quando un creator va in diretta, avviare registrazione o statistiche appena parte la LIVE, aprire una connessione WebSocket per chat e regali solo mentre il creator è davvero in diretta, o tenere aggiornato lo stato live del roster di un'agenzia.

Come funziona

1. Registra un webhook con l'URL del tuo endpoint, gli eventi che vuoi e gli username TikTok da seguire.
2. Conserva il segreto di firma, restituito una sola volta alla creazione. Ogni consegna viene firmata con questo.
3. Ricevi live.start e live.end come POST JSON. Verifica la firma, rispondi 200, poi fai il tuo lavoro.

Eventi

Registra un webhook

Crea i webhook dalla dashboard, oppure da server a server con la tua chiave API. La risposta include il segreto di firma, mostrato una sola volta.

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.

Limita creators agli account che ti interessano (fino a 1.000 per webhook). Per cambiare la lista in seguito, aggiorna il webhook con PATCH passando il nuovo array completo: sostituisce la lista precedente. Tutti i parametri sono nel riferimento API.

Payload

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

Ogni consegna porta anche gli header X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt e X-Tiktool-Webhook-Id.

Verifica la firma

Ogni POST include X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, dove v1 è l'HMAC-SHA256 di "<t>.<raw body>" calcolato con il segreto del tuo webhook. Calcolalo sul body grezzo prima di fare il parsing del JSON, confronta in tempo costante e rifiuta i timestamp più vecchi di cinque minuti.

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)

Consegna e nuovi tentativi

• Almeno una volta. Lo stesso evento può arrivare più di una volta, quindi deduplica su event_id.
• Nuovi tentativi. Una consegna fallita viene ritentata secondo lo schema 0s, 30s, 2m, 10m, 1h e 6h. Dopo l'ultimo tentativo resta come dead letter, che puoi rinviare dalla dashboard o dall'API quando il tuo endpoint torna operativo.
• Rispondi subito. Restituisci un 2xx appena arriva la POST ed elabora dopo. Il timeout di connessione è di 10 secondi e quello di lettura di 15 secondi; una connessione rifiutata o un timeout contano come tentativo fallito.
• Testa quando vuoi. Invia una consegna di test firmata al tuo endpoint dalla dashboard o dall'endpoint di test, per controllare parsing e firma prima che un creator vada in diretta.

Piani

I webhook con live.start e live.end sono inclusi in ogni piano a pagamento, con più endpoint e più consegne giornaliere nei piani superiori. Un account Sandbox può configurare un webhook di test dalla dashboard e inviargli consegne di test firmate, così puoi costruire l'integrazione prima di abbonarti. Le consegne reali e la registrazione dei webhook con una chiave API richiedono un piano a pagamento. Vedi i prezzi per i dettagli dei piani.

Domande frequenti