TikTok LIVE Webhook 能做什麼
Webhook 就是送到你伺服器的開播通知。我們會盯著你列出的直播主，當其中有人開始 LIVE（live.start）以及直播結束時（live.end），對你的網址發送 HTTPS POST。你的服務不需要一直保持連線或跑排程，只要回應 POST 就好。
常見用法：直播主開播時發到 Discord 或 Slack、直播一開始就啟動錄影或分析、只在直播主真的在播時才開啟WebSocket 連線接收聊天和禮物，或讓公會旗下名單的直播狀態保持最新。
運作方式
- 註冊 Webhook，填入你的端點網址、想要的事件和要追蹤的 TikTok 使用者名稱。
- 保存簽章密鑰，建立時只會回傳一次。每次送達都會用它簽章。
- 接收 live.start 和 live.end，以 JSON POST 送達。驗證簽章、回應 200，再做你的處理。
事件
| 事件 | 方案 | 觸發時機 |
|---|---|---|
live.start | 所有付費方案 | 追蹤中的直播主開始 LIVE。包含直播間 ID、開始時間和直播網址。 |
live.end | 所有付費方案 | 追蹤中的直播主結束直播。格式相同，附結束時間。 |
live.peak_viewers | Ultra 和 Agency Global | 直播創下新的觀眾高峰。 |
live.gift.high_value | Ultra 和 Agency Global | 追蹤中的直播收到高價禮物。 |
creator.follower_milestone | Agency Global | 追蹤中的直播主粉絲數突破里程碑。 |
註冊 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 只放你在意的帳號就好（每個 Webhook 最多 1,000 個）。之後要改名單，用完整的新陣列對 Webhook 執行 PATCH，它會取代原本的名單。完整參數請看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" }
}每次送達也會帶上 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 是以你的 Webhook 密鑰對 "<t>.<raw body>" 計算的 HMAC-SHA256。請在解析 JSON 之前對原始 body 計算、用固定時間比對，並拒絕超過五分鐘的時間戳記。
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 重送。
- 快速回應。POST 一到就先回 2xx，之後再處理。連線逾時為 10 秒、讀取逾時為 15 秒；連線被拒或逾時都算一次失敗。
- 隨時測試。在直播主開播前，可從主控台或測試端點對你的端點發送已簽章的測試送達，檢查解析和簽章處理。
方案
live.start 和 live.end 的 Webhook 包含在所有付費方案中，方案越高，端點越多、每日送達額度也越大。Sandbox 帳號可以在主控台設定一個測試 Webhook 並發送已簽章的測試送達，訂閱前就能先把整合做好。正式送達以及用 API 金鑰註冊 Webhook 需要付費方案。方案細節請看價格。