TikTok LIVE Webhook

Apa yang dilakukan webhook TikTok LIVE

Webhook adalah notifikasi mulai live yang dikirim ke server kamu. Kami memantau kreator yang kamu daftarkan dan mengirim HTTPS POST ke URL kamu saat salah satunya mulai LIVE (live.start) dan lagi saat siarannya selesai (live.end). Layanan kamu tidak perlu menahan koneksi tetap terbuka atau menjalankan scheduler - cukup menjawab sebuah POST.

Penggunaan umum: kirim pesan ke Discord atau Slack saat kreator mulai live, mulai merekam atau menjalankan analitik begitu siaran dimulai, buka koneksi WebSocket untuk chat dan hadiah hanya selama kreator benar-benar live, atau jaga status live roster agency tetap terbaru.

Cara kerjanya

1. Daftarkan webhook dengan URL endpoint kamu, event yang kamu mau, dan username TikTok yang ingin dipantau.
2. Simpan signing secret yang dikembalikan sekali saat dibuat. Setiap pengiriman ditandatangani dengannya.
3. Terima live.start dan live.end sebagai POST JSON. Verifikasi tanda tangannya, jawab 200, lalu kerjakan prosesnya.

Event

Daftarkan webhook

Buat webhook dari dasbor, atau server-to-server dengan API key kamu. Respons berisi signing secret, yang hanya ditampilkan sekali.

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.

Batasi creators ke akun yang kamu pedulikan saja (hingga 1.000 per webhook). Untuk mengubah daftarnya nanti, PATCH webhook dengan array baru yang lengkap - daftar sebelumnya akan diganti. Parameter lengkapnya ada di referensi 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" }
}

Setiap pengiriman juga membawa header X-Tiktool-Timestamp, X-Tiktool-Event, X-Tiktool-Event-Id, X-Tiktool-Delivery-Id, X-Tiktool-Attempt, dan X-Tiktool-Webhook-Id.

Verifikasi tanda tangan

Setiap POST menyertakan X-Tiktool-Signature: t=<unix_ts>,v1=<hex>, dengan v1 adalah HMAC-SHA256 dari "<t>.<raw body>" yang dikunci dengan secret webhook kamu. Hitung dari raw body sebelum mem-parse JSON, bandingkan dalam waktu konstan, dan tolak timestamp yang lebih lama dari lima menit.

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)

Pengiriman dan retry

• Minimal sekali. Event yang sama bisa datang lebih dari sekali, jadi lakukan dedupe berdasarkan event_id.
• Retry. Pengiriman yang gagal dicoba ulang dengan jadwal 0 dtk, 30 dtk, 2 mnt, 10 mnt, 1 jam, dan 6 jam. Setelah percobaan terakhir, event disimpan sebagai dead letter yang bisa kamu replay dari dasbor atau API begitu endpoint kamu sehat lagi.
• Jawab cepat. Kembalikan 2xx begitu POST masuk, lalu proses setelahnya. Connect timeout 10 detik dan read timeout 15 detik; koneksi yang ditolak atau timeout dihitung sebagai percobaan gagal.
• Uji kapan saja. Kirim pengiriman uji bertanda tangan ke endpoint kamu dari dasbor atau endpoint test untuk mengecek parsing dan penanganan tanda tangan sebelum kreator mulai live.

Paket

Webhook dengan live.start dan live.end sudah termasuk di semua paket berbayar, dengan lebih banyak endpoint dan jatah pengiriman harian yang lebih besar di paket yang lebih tinggi. Akun Sandbox bisa menyiapkan satu webhook uji dari dasbor dan mengirim pengiriman uji bertanda tangan ke sana, jadi integrasinya bisa dibangun sebelum kamu berlangganan. Pengiriman live, serta pendaftaran webhook dengan API key, butuh paket berbayar. Lihat harga untuk detail paket.

Pertanyaan yang Sering Diajukan