TikTok LIVE Webhook 能做什么
Webhook 是推送到你服务器的开播提醒。我们会关注你列出的主播，当其中有人开播时（live.start）向你的 URL 发送一条 HTTPS POST，直播结束时（live.end）再发送一次。你的服务无需保持连接或运行定时任务，只要响应 POST 即可。
典型用法：主播开播时发消息到 Discord 或 Slack；直播一开始就启动录制或数据分析；只在主播真正开播时才打开WebSocket 连接接收弹幕和礼物；或者让公会主播名单的开播状态保持最新。
工作原理
- 注册 Webhook：填写你的端点 URL、要订阅的事件以及要关注的 TikTok 用户名。
- 保存签名密钥：它只在创建时返回一次，每次推送都会用它签名。
- 接收 live.start 和 live.end：以 JSON POST 形式送达。先校验签名，返回 200，再处理业务逻辑。
事件
| 事件 | 套餐 | 触发时机 |
|---|---|---|
live.start | 所有付费套餐 | 关注的主播开播了，包含直播间 ID、开播时间和直播链接。 |
live.end | 所有付费套餐 | 关注的主播结束了直播，结构相同，附带下播时间。 |
live.peak_viewers | Ultra 和 Agency Global | 直播观众数创下新高。 |
live.gift.high_value | Ultra 和 Agency Global | 关注的直播中出现了高价值礼物。 |
creator.follower_milestone | Agency Global | 关注的主播粉丝数达到了新的里程碑。 |
注册 Webhook
可以在控制台创建 Webhook，也可以用 API Key 从服务器端创建。响应中包含签名密钥，仅显示一次。
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 个）。之后要修改名单，用完整的新数组 PATCH 该 Webhook，它会替换原有名单。完整参数见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 之前基于原始请求体计算，使用恒定时间比较，并拒绝超过五分钟的时间戳。
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去重。 - 重试。推送失败后会按 0s、30s、2m、10m、1h、6h 的间隔重试。最后一次尝试后，事件会保留为死信，等你的端点恢复正常后，可以从控制台或 API 重放。
- 快速响应。收到 POST 后立即返回 2xx，之后再处理。连接超时 10 秒，读取超时 15 秒；连接被拒绝或超时都算一次失败尝试。
- 随时测试。在主播开播之前，你可以从控制台或测试接口向你的端点发送一条带签名的测试推送，检查解析和签名处理是否正确。
套餐
所有付费套餐都包含 live.start 和 live.end Webhook，更高的套餐提供更多端点和更高的每日推送额度。Sandbox 账号可以在控制台设置一个测试 Webhook 并向它发送带签名的测试推送，在订阅之前就能完成集成。真实推送以及用 API Key 注册 Webhook 需要付费套餐。套餐详情见价格页。