TikTok LIVE Webhooks

Τι κάνει ένα TikTok LIVE webhook

Ένα webhook είναι μια ειδοποίηση live που φτάνει στον server σου. Παρακολουθούμε τους creators της λίστας σου και στέλνουμε HTTPS POST στο URL σου όταν κάποιος ξεκινά LIVE (live.start) και ξανά όταν τελειώνει το stream (live.end). Η υπηρεσία σου δεν χρειάζεται να κρατά ανοιχτή σύνδεση ή να τρέχει scheduler - αρκεί να απαντά σε ένα POST.

Συνηθισμένες χρήσεις: ποστάρισμα σε Discord ή Slack όταν ένας creator βγαίνει live, έναρξη εγγραφής ή analytics τη στιγμή που ξεκινά το stream, άνοιγμα σύνδεσης WebSocket για chat και δώρα μόνο όσο ο creator είναι πραγματικά live, ή ενημερωμένο live status για το ρόστερ ενός agency.

Πώς δουλεύει

1. Κάνε εγγραφή ενός webhook με το URL του endpoint σου, τα events που θέλεις και τα usernames του TikTok που θα παρακολουθείς.
2. Φύλαξε το signing secret που επιστρέφεται μία φορά κατά τη δημιουργία. Κάθε παράδοση υπογράφεται με αυτό.
3. Λάβε live.start και live.end ως JSON POSTs. Έλεγξε την υπογραφή, απάντησε 200 και μετά κάνε τη δουλειά σου.

Events

Εγγραφή webhook

Δημιούργησε webhooks από το dashboard ή server-to-server με το API key σου. Η απάντηση περιέχει το signing secret, που εμφανίζεται μόνο μία φορά.

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 ανά webhook). Για να αλλάξεις τη λίστα αργότερα, κάνε PATCH στο webhook με ολόκληρο τον νέο πίνακα - αντικαθιστά την προηγούμενη λίστα. Όλες οι παράμετροι υπάρχουν στην αναφορά API.

Payloads

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" }
}

Κάθε παράδοση έχει επίσης τα headers 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 είναι το HMAC-SHA256 του "<t>.<raw body>" με κλειδί το webhook secret σου. Υπολόγισέ το πάνω στο raw body πριν κάνεις parse το JSON, σύγκρινε σε σταθερό χρόνο και απόρριψε timestamps παλαιότερα από πέντε λεπτά.

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 μπορεί να φτάσει πάνω από μία φορά, οπότε κάνε dedupe με βάση το event_id.
• Επαναλήψεις. Μια αποτυχημένη παράδοση ξαναδοκιμάζεται με πρόγραμμα 0s, 30s, 2m, 10m, 1h και 6h. Μετά την τελευταία προσπάθεια κρατιέται ως dead letter, που μπορείς να κάνεις replay από το dashboard ή το API μόλις το endpoint σου είναι ξανά εντάξει.
• Απάντα γρήγορα. Επίστρεψε 2xx μόλις φτάσει το POST και κάνε την επεξεργασία μετά. Το connect timeout είναι 10 δευτερόλεπτα και το read timeout 15 δευτερόλεπτα· μια σύνδεση που απορρίπτεται ή ένα timeout μετράει ως αποτυχημένη προσπάθεια.
• Δοκίμασε όποτε θέλεις. Στείλε μια υπογεγραμμένη δοκιμαστική παράδοση στο endpoint σου από το dashboard ή το test endpoint, για να ελέγξεις το parsing και την υπογραφή πριν βγει live κάποιος creator.

Πακέτα

Τα webhooks με live.start και live.end περιλαμβάνονται σε κάθε επί πληρωμή πακέτο, με περισσότερα endpoints και μεγαλύτερο ημερήσιο όριο παραδόσεων στα μεγαλύτερα πακέτα. Ένας λογαριασμός Sandbox μπορεί να στήσει ένα δοκιμαστικό webhook από το dashboard και να του στέλνει υπογεγραμμένες δοκιμαστικές παραδόσεις, ώστε να φτιάξεις το integration πριν γραφτείς συνδρομητής. Οι πραγματικές παραδόσεις και η εγγραφή webhooks με API key θέλουν επί πληρωμή πακέτο. Δες τις τιμές για λεπτομέρειες.

Συχνές ερωτήσεις