Webhooks de TikTok LIVE

Qué hace un webhook de TikTok LIVE

Un webhook es una alerta de inicio de LIVE que llega a tu servidor. Vigilamos a los creadores de tu lista y enviamos un POST HTTPS a tu URL cuando uno de ellos empieza un LIVE (live.start) y otra vez cuando termina la transmisión (live.end). Tu servicio no necesita mantener una conexión abierta ni ejecutar un programador de tareas: solo tiene que responder a un POST.

Usos típicos: publicar en Discord o Slack cuando un creador entra en vivo, empezar a grabar o a medir en cuanto arranca una transmisión, abrir una conexión WebSocket para el chat y los regalos solo mientras el creador está en vivo, o mantener al día el estado LIVE del roster de una agencia.

Cómo funciona

1. Registra un webhook con la URL de tu endpoint, los eventos que quieres y los usuarios de TikTok a vigilar.
2. Guarda el secreto de firma que se devuelve una sola vez al crearlo. Cada entrega se firma con él.
3. Recibe live.start y live.end como POSTs JSON. Verifica la firma, responde 200 y luego haz tu trabajo.

Eventos

Registra un webhook

Crea webhooks desde el panel, o de servidor a servidor con tu API key. La respuesta incluye el secreto de firma, que se muestra una sola 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.

Limita creators a las cuentas que te interesan (hasta 1,000 por webhook). Para cambiar la lista después, haz PATCH al webhook con el nuevo array completo: reemplaza la lista anterior. Todos los parámetros están en la referencia de la 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" }
}

Cada entrega también lleva los headers X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt y X-Tiktool-Webhook-Id.

Verifica la firma

Cada POST incluye X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, donde v1 es el HMAC-SHA256 de "<t>.<raw body>" con tu secreto del webhook como clave. Calcúlalo sobre el body sin procesar antes de parsear el JSON, compara en tiempo constante y rechaza las marcas de tiempo de más 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 y reintentos

• Al menos una vez. El mismo evento puede llegar más de una vez, así que elimina duplicados con event_id.
• Reintentos. Una entrega fallida se reintenta según este calendario: 0s, 30s, 2m, 10m, 1h y 6h. Después del último intento se guarda como entrega fallida (dead letter) que puedes reenviar desde el panel o la API cuando tu endpoint vuelva a funcionar.
• Responde rápido. Devuelve un 2xx en cuanto llegue el POST y procesa después. El tiempo de espera de conexión es de 10 segundos y el de lectura de 15 segundos; una conexión rechazada o un timeout cuenta como intento fallido.
• Prueba cuando quieras. Envía una entrega de prueba firmada a tu endpoint desde el panel o el endpoint de pruebas para comprobar el parseo y la verificación de la firma antes de que un creador entre en vivo.

Planes

Los webhooks con live.start y live.end están incluidos en todos los planes de pago, con más endpoints y más entregas diarias en los planes superiores. Una cuenta Sandbox puede configurar un webhook de prueba desde el panel y enviarle entregas de prueba firmadas, así puedes crear la integración antes de suscribirte. Las entregas reales y el registro de webhooks con API key requieren un plan de pago. Consulta los precios para ver los detalles de cada plan.

Preguntas frecuentes