TikTok LIVE Webhook

TikTok LIVE webhook làm gì

Webhook là thông báo lên live được gửi tới server của bạn. Chúng tôi theo dõi các nhà sáng tạo bạn liệt kê và gửi HTTPS POST tới URL của bạn khi một người bắt đầu LIVE (live.start) và một lần nữa khi phiên live kết thúc (live.end). Dịch vụ của bạn không cần giữ kết nối mở hay chạy lịch định kỳ - chỉ cần trả lời một POST.

Cách dùng phổ biến: đăng lên Discord hoặc Slack khi nhà sáng tạo lên live, bắt đầu ghi hình hoặc thống kê ngay khi phiên live bắt đầu, mở kết nối WebSocket để lấy chat và quà tặng chỉ trong lúc nhà sáng tạo thật sự đang live, hoặc giữ trạng thái live của danh sách idol trong agency luôn cập nhật.

Cách hoạt động

1. Đăng ký webhook với URL endpoint, các sự kiện bạn muốn nhận và các username TikTok cần theo dõi.
2. Lưu signing secret được trả về một lần khi tạo. Mọi lần gửi đều được ký bằng nó.
3. Nhận live.start và live.end dưới dạng POST JSON. Xác minh chữ ký, trả về 200, rồi mới xử lý.

Sự kiện

Đăng ký webhook

Tạo webhook từ bảng điều khiển, hoặc server-to-server bằng API key. Phản hồi có kèm signing secret, chỉ hiển thị một lần.

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.

Giữ creators chỉ gồm những tài khoản bạn quan tâm (tối đa 1.000 mỗi webhook). Muốn đổi danh sách sau này, hãy PATCH webhook với toàn bộ mảng mới - nó sẽ thay thế danh sách cũ. Tham số đầy đủ có trong tài liệu 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" }
}

Mỗi lần gửi còn kèm các header X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt và X-Tiktool-Webhook-Id.

Xác minh chữ ký

Mỗi POST có X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, trong đó v1 là HMAC-SHA256 của "<t>.<raw body>" với khóa là webhook secret của bạn. Hãy tính trên raw body trước khi parse JSON, so sánh theo thời gian hằng định, và từ chối timestamp cũ hơn năm phút.

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)

Gửi và thử lại

• Ít nhất một lần. Cùng một sự kiện có thể tới nhiều lần, nên hãy loại trùng theo event_id.
• Thử lại. Lần gửi thất bại sẽ được thử lại theo lịch 0s, 30s, 2m, 10m, 1h và 6h. Sau lần thử cuối, nó được giữ lại dưới dạng dead letter để bạn phát lại từ bảng điều khiển hoặc API khi endpoint đã ổn định.
• Phản hồi nhanh. Trả về 2xx ngay khi POST tới rồi mới xử lý sau. Timeout kết nối là 10 giây và timeout đọc là 15 giây; kết nối bị từ chối hoặc hết thời gian đều tính là một lần thất bại.
• Test bất cứ lúc nào. Gửi một lần test có chữ ký tới endpoint của bạn từ bảng điều khiển hoặc endpoint test để kiểm tra việc parse và xử lý chữ ký trước khi nhà sáng tạo lên live.

Các gói

Webhook với live.start và live.end có trong mọi gói trả phí, gói càng cao càng có nhiều endpoint và hạn mức gửi mỗi ngày lớn hơn. Tài khoản Sandbox có thể tạo một webhook test từ bảng điều khiển và gửi các lần test có chữ ký tới đó, để bạn xây xong tích hợp trước khi đăng ký. Gửi thật và đăng ký webhook bằng API key cần gói trả phí. Xem bảng giá để biết chi tiết các gói.

Câu hỏi thường gặp