TikTok LIVE Webhookでできること
Webhookは、あなたのサーバーに届く配信開始の通知です。登録したクリエイターを私たちが見守り、誰かがLIVEを始めたとき（live.start）と配信を終えたとき（live.end）に、あなたのURLへHTTPS POSTを送ります。あなたのサービスは接続を開いたままにしたり、スケジューラーを動かしたりする必要はなく、POSTに応答するだけです。
よくある使い方: クリエイターが配信を始めたらDiscordやSlackに投稿する、配信が始まった瞬間に録画や分析を開始する、クリエイターが実際に配信している間だけチャットとギフトのためにWebSocket接続を開く、エージェンシーの所属リストの配信状況を最新に保つ、など。
仕組み
- エンドポイントのURL、受け取りたいイベント、見守るTikTokユーザー名を指定してWebhookを登録します。
- 作成時に一度だけ返される署名シークレットを保管してください。すべての配信はこれで署名されます。
- live.startとlive.endがJSONのPOSTで届きます。署名を検証して200で応答してから、処理を行ってください。
イベント
| イベント | プラン | 発火するタイミング |
|---|---|---|
live.start | すべての有料プラン | 見守っているクリエイターがLIVEを始めました。ルームID、開始時刻、配信URLを含みます。 |
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リファレンスにあります。
ペイロード
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で重複を除いてください。 - リトライ。 失敗した配信は、0秒、30秒、2分、10分、1時間、6時間のスケジュールでリトライされます。最後の試行のあとはデッドレターとして保管され、エンドポイントが復旧したらダッシュボードかAPIから再送できます。
- すばやく応答。 POSTが届いたらすぐに2xxを返し、処理はそのあとで行ってください。接続タイムアウトは10秒、読み取りタイムアウトは15秒です。接続拒否やタイムアウトは失敗した試行として扱われます。
- いつでもテスト可能。 クリエイターが配信を始める前に、ダッシュボードかテスト用エンドポイントから署名付きのテスト配信をエンドポイントに送って、解析と署名の処理を確認できます。
プラン
live.startとlive.endのWebhookはすべての有料プランに含まれ、上位プランほどエンドポイント数と一日の配信上限が増えます。Sandboxアカウントでもダッシュボードからテスト用Webhookを一つ設定して署名付きのテスト配信を送れるので、登録前に連携を作っておけます。実際の配信と、APIキーでのWebhook登録には有料プランが必要です。プランの詳細は料金をご覧ください。