TikTok LIVE Webhooks

O que um webhook do TikTok LIVE faz

Um webhook é um alerta de início de live entregue no seu servidor. Nós acompanhamos os criadores da sua lista e enviamos um POST HTTPS para a sua URL quando um deles inicia uma LIVE (live.start) e de novo quando a live termina (live.end). Seu serviço não precisa manter uma conexão aberta nem rodar um agendador - só precisa responder a um POST.

Usos comuns: postar no Discord ou no Slack quando um criador entra ao vivo, começar a gravar ou a coletar analytics no momento em que a live começa, abrir uma conexão WebSocket para chat e presentes só enquanto o criador estiver ao vivo de verdade, ou manter atualizado o status de live do elenco de uma agência.

Como funciona

1. Cadastre um webhook com a URL do seu endpoint, os eventos que você quer e os usuários do TikTok para acompanhar.
2. Guarde o segredo de assinatura retornado uma única vez na criação. Toda entrega é assinada com ele.
3. Receba live.start e live.end como POSTs em JSON. Verifique a assinatura, responda 200 e depois faça o seu trabalho.

Eventos

Cadastre um webhook

Crie webhooks pelo painel ou de servidor para servidor com sua chave de API. A resposta inclui o segredo de assinatura, mostrado uma única vez.

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.

Deixe creators só com as contas que importam para você (até 1.000 por webhook). Para mudar a lista depois, faça um PATCH no webhook com o novo array completo - ele substitui a lista anterior. Todos os parâmetros estão na referência da 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" }
}

Toda entrega também traz os headers X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt e X-Tiktool-Webhook-Id.

Verifique a assinatura

Cada POST inclui X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, em que v1 é o HMAC-SHA256 de "<t>.<raw body>" com o segredo do seu webhook como chave. Calcule sobre o corpo bruto antes de fazer o parse do JSON, compare em tempo constante e rejeite timestamps com mais de cinco minutos.

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)

Entrega e novas tentativas

• Pelo menos uma vez. O mesmo evento pode chegar mais de uma vez, então remova duplicados pelo event_id.
• Novas tentativas. Uma entrega que falha é tentada de novo seguindo a sequência 0s, 30s, 2min, 10min, 1h e 6h. Depois da última tentativa, ela fica guardada como dead letter, e você pode reenviar pelo painel ou pela API quando o seu endpoint voltar ao normal.
• Responda rápido. Retorne um 2xx assim que o POST chegar e processe depois. O timeout de conexão é de 10 segundos e o de leitura, 15 segundos; conexão recusada ou timeout contam como tentativa falha.
• Teste quando quiser. Envie uma entrega de teste assinada para o seu endpoint pelo painel ou pelo endpoint de teste, para conferir o parse e a verificação da assinatura antes de um criador entrar ao vivo.

Planos

Webhooks com live.start e live.end estão incluídos em todo plano pago, com mais endpoints e uma cota diária de entregas maior nos planos mais altos. Uma conta Sandbox pode configurar um webhook de teste pelo painel e enviar entregas de teste assinadas para ele, então dá para construir a integração antes de assinar. Entregas reais e o cadastro de webhooks com chave de API exigem um plano pago. Veja os detalhes dos planos em preços.

Perguntas frequentes