TikTok LIVE Webhooks

ما الذي يفعله TikTok LIVE webhook

الـ webhook تنبيه ببدء البث يصل إلى خادمك. نراقب صناع المحتوى الذين تحددهم ونرسل طلب HTTPS POST إلى رابطك عندما يبدأ أحدهم بث LIVE (live.start) ومرة أخرى عندما ينتهي البث (live.end). لا تحتاج خدمتك إلى إبقاء اتصال مفتوح أو تشغيل جدولة، يكفي أن ترد على طلب POST.

استخدامات شائعة: النشر في Discord أو Slack عندما يبدأ صانع محتوى البث، أو بدء التسجيل أو التحليلات لحظة بدء البث، أو فتح اتصال WebSocket للدردشة والهدايا فقط أثناء بث صانع المحتوى فعليًا، أو إبقاء حالة البث لقائمة الوكالة محدّثة.

كيف يعمل

1. سجّل webhook برابط نقطة الاتصال الخاصة بك، والأحداث التي تريدها، وأسماء مستخدمي TikTok التي تريد مراقبتها.
2. احفظ مفتاح التوقيع السري الذي يُعاد مرة واحدة عند الإنشاء. كل إرسال يُوقَّع به.
3. استقبل live.start و live.end كطلبات POST بصيغة JSON. تحقق من التوقيع، ورد بـ 200، ثم نفّذ عملك.

الأحداث

سجّل webhook

أنشئ webhooks من لوحة التحكم، أو من خادم إلى خادم باستخدام مفتاح 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 لكل webhook). لتغيير القائمة لاحقًا، أرسل PATCH إلى الـ webhook مع المصفوفة الجديدة كاملة، فهي تستبدل القائمة السابقة. المعاملات الكاملة في مرجع 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 هو HMAC-SHA256 لـ "<t>.<raw body>" باستخدام المفتاح السري للـ webhook. احسبه على النص الخام قبل تحليل 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 عندما تعود نقطة الاتصال للعمل.
• رد بسرعة. أعد رمز 2xx فور وصول طلب POST وعالجه بعد ذلك. مهلة الاتصال 10 ثوانٍ ومهلة القراءة 15 ثانية، والاتصال المرفوض أو انتهاء المهلة يُحتسب محاولة فاشلة.
• اختبر في أي وقت. أرسل إرسالًا تجريبيًا موقّعًا إلى نقطة الاتصال الخاصة بك من لوحة التحكم أو من نقطة اتصال الاختبار، لتتحقق من التحليل ومعالجة التوقيع قبل أن يبدأ صانع محتوى البث.

الباقات

الـ Webhooks مع live.start و live.end مشمولة في كل باقة مدفوعة، مع نقاط اتصال أكثر وحصة إرسال يومية أكبر في الباقات الأعلى. يمكن لحساب Sandbox إعداد webhook تجريبي واحد من لوحة التحكم وإرسال إرسالات تجريبية موقّعة إليه، لتبني التكامل قبل الاشتراك. الإرسالات الفعلية، وتسجيل webhooks بمفتاح API، تتطلب باقة مدفوعة. راجع الأسعار لتفاصيل الباقات.

الأسئلة الشائعة