TikTok LIVE 웹훅이 하는 일
웹훅은 내 서버로 전달되는 방송 시작 알림이에요. 등록한 크리에이터를 지켜보다가, 그중 누군가 LIVE를 시작하면(live.start) 내 URL로 HTTPS POST를 보내고, 방송이 끝나면(live.end) 한 번 더 보내요. 내 서비스는 연결을 계속 열어 두거나 스케줄러를 돌릴 필요 없이 POST에 응답만 하면 돼요.
대표적인 활용: 크리에이터가 라이브를 시작하면 디스코드나 Slack에 알림 올리기, 방송이 시작되는 순간 녹화나 분석 시작하기, 크리에이터가 실제로 라이브 중일 때만 채팅과 선물용 WebSocket 연결 열기, 에이전시 소속 크리에이터의 라이브 상태를 최신으로 유지하기.
작동 방식
- 웹훅 등록: 엔드포인트 URL, 받을 이벤트, 지켜볼 TikTok 사용자 이름을 입력하세요.
- 서명 시크릿 저장: 생성할 때 한 번만 보여 줘요. 모든 전송에 이 시크릿으로 서명해요.
- 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 | 지켜보는 크리에이터가 팔로워 목표치를 넘었어요. |
웹훅 등록
대시보드에서 웹훅을 만들거나, 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 목록에는 관심 있는 계정만 넣으세요 (웹훅당 최대 1,000개). 나중에 목록을 바꾸려면 새 배열 전체로 웹훅에 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 값은 웹훅 시크릿을 키로 "<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 웹훅은 모든 유료 요금제에 포함되며, 상위 요금제일수록 엔드포인트 수와 하루 전송 허용량이 늘어나요. Sandbox 계정도 대시보드에서 테스트 웹훅 하나를 설정하고 서명된 테스트 전송을 보낼 수 있어서, 구독 전에 연동을 미리 만들어 둘 수 있어요. 실제 전송과 API 키로 웹훅을 등록하려면 유료 요금제가 필요해요. 요금제 상세 내용은 가격 페이지에서 확인하세요.