TikTok LIVE Webhook

Что делает webhook TikTok LIVE

Webhook - это уведомление о начале эфира, которое приходит на ваш сервер. Мы следим за стримерами из вашего списка и отправляем HTTPS POST на ваш URL, когда кто-то из них начинает LIVE (live.start), и ещё раз, когда трансляция заканчивается (live.end). Вашему сервису не нужно держать открытое подключение или запускать планировщик - достаточно ответить на POST.

Типичные сценарии: пост в Discord или Slack, когда стример выходит в эфир; запуск записи или аналитики в момент начала стрима; WebSocket-подключение для чата и подарков только пока стример действительно в эфире; актуальный статус эфира для ростера агентства.

Как это работает

1. Зарегистрируйте webhook: укажите URL эндпоинта, нужные события и никнеймы TikTok для отслеживания.
2. Сохраните секрет подписи - он показывается один раз при создании. Каждая доставка подписывается им.
3. Получайте live.start и live.end в виде JSON POST-запросов. Проверьте подпись, ответьте 200, потом делайте свою работу.

События

Регистрация webhook

Создавайте webhook в панели или через сервер с вашим API-ключом. В ответе есть секрет подписи - он показывается только один раз.

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.

Ограничьте creators только нужными аккаунтами (до 1 000 на один webhook). Чтобы потом изменить список, отправьте PATCH для webhook с полным новым массивом - он заменит прежний список. Все параметры - в справочнике API.

Содержимое запросов

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

Каждая доставка также содержит заголовки X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt и X-Tiktool-Webhook-Id.

Проверка подписи

Каждый POST содержит X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, где v1 - это HMAC-SHA256 от "<t>.<raw body>" с ключом-секретом вашего webhook. Считайте его по сырому телу до разбора JSON, сравнивайте за постоянное время и отклоняйте метки времени старше пяти минут.

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)

Доставка и повторы

• Как минимум один раз. Одно и то же событие может прийти несколько раз, поэтому убирайте дубли по event_id.
• Повторы. Неудачная доставка повторяется по расписанию: 0 с, 30 с, 2 мин, 10 мин, 1 ч и 6 ч. После последней попытки событие сохраняется как недоставленное - его можно отправить повторно из панели или через API, когда ваш эндпоинт снова заработает.
• Отвечайте быстро. Возвращайте 2xx сразу, как только пришёл POST, а обрабатывайте потом. Таймаут подключения - 10 секунд, таймаут чтения - 15 секунд; отказ в подключении или таймаут считаются неудачной попыткой.
• Тестируйте в любой момент. Отправьте подписанную тестовую доставку на свой эндпоинт из панели или через тестовый эндпоинт, чтобы проверить разбор и подпись до того, как стример выйдет в эфир.

Тарифы

Webhook с live.start и live.end входят в любой платный тариф, а на старших тарифах больше эндпоинтов и выше дневной лимит доставок. Аккаунт Sandbox может настроить один тестовый webhook в панели и отправлять на него подписанные тестовые доставки, так что интеграцию можно собрать ещё до подписки. Для реальных доставок и регистрации webhook через API-ключ нужен платный тариф. Подробности о тарифах - на странице цен.

Частые вопросы