إعداد webhooks الخاصة بـ TikTok API for Business
تُرسل TikTok API for Business خطافات الويب (webhooks) إلى عنوان استدعاء URL واحد لكل تطبيق مطوّر ولكل نوع حدث، ويُضبط ذلك بطلب POST إلى /business/webhook/update/ باستخدام app_id وsecret الخاص بالتطبيق. يشترك event_type بقيمة VIDEO في أحداث النشر الأربعة للمنشورات، ويشترك COMMENT في comment.update. يصل كل إرسال كطلب HTTPS بطريقة POST موقّع في ترويسة Tiktok-Signature، ويُحسب بخوارزمية HMAC-SHA256 بمفتاح هو سر التطبيق.
يحتفظ easyCoexistence باشتراك webhook التعليقات الخاص بـ TikTok لتطبيقه، ويتحقق من توقيع TikTok، ويمرر كل حدث تعليق لحسابك إلى نقطة النهاية HTTPS الخاصة بك، موقّعا بسر خاص به.
المدة التي تعيد فيها TikTok محاولة الإرسال الذي لم يتلقَّ ردا برمز HTTP 200، مع تأخير متصاعد أُسّيًا، قبل حذفه.
أكبر عدد من معرّفات المنشورات يمكن أن يحددها item_list الواحدة لقصر أحداث comment.update على منشورات بعينها.
القيمة الحالية لترويسة webhook-schema-version التي ترسلها TikTok مع كل إرسال.
ما تذكره مرجعية TikTok لنقاط النهاية (endpoints) الخاصة بإعداد webhooks، وهي تتحقق بمعرّف التطبيق وسره.
الخوارزمية وراء Tiktok-Signature: الطابع الزمني ثم نقطة ثم نص الطلب، موقّعة بسر التطبيق ومرمّزة بالنظام السداسي عشري (hex).
الصلاحية التي يحتاجها التطبيق ضمن TikTok Accounts لأحداث comment.update، أما أحداث النشر فتحتاج Business Content.
ما أحداث webhooks التي يمكن لتطبيق حساب TikTok استقبالها؟
فئتان، يُشترك في كل منهما بنوع حدث مستقل event_type. تشمل VIDEO المنشورات المنشورة عبر /business/video/publish/ أو /business/photo/publish/، وتشمل COMMENT التعليقات على منشورات الصور في الحساب ومنشورات الفيديو العامة، سواء نُشرت عبر الواجهة أو داخل تطبيق TikTok:
ما الذي يحتاجه التطبيق قبل الاشتراك؟
الوصول إلى API for Business، وتطبيق مطوّر، وحسابات TikTok فوّضت التطبيق. يضيف دليل الاشتراك في TikTok صلاحية لكل فئة، ويحتاج حدث التعليق نطاقا يمنحه المالك:
- أحداث النشر: صلاحية TikTok Accounts وBusiness Content على التطبيق.
- أحداث التعليقات: صلاحية TikTok Accounts وBusiness Comment على التطبيق.
- comment.update: النطاق comment.list، يمنحه المالك ويبقى ساريا.
- عنوان URL للاستدعاء يعمل عبر HTTPS ويرد برمز HTTP 200 فورا.
كيف تشترك؟
بطلب POST إلى /business/webhook/update/، مرة لكل event_type. يأخذ الجسم app_id وsecret وevent_type، أي VIDEO أو COMMENT، وcallback_url؛ وفي حالة COMMENT يمكنه أيضا أخذ item_list. تعيد الاستجابة app_id وevent_type وcallback_url، وكذلك item_list عند ضبطها. وإعادة الاستدعاء لنفس event_type تستبدل عنوان الاستدعاء.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "<APP_ID>",
"secret": "<APP_SECRET>",
"event_type": "COMMENT",
"callback_url": "https://hooks.example.com/tiktok/"
}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}كيف تُضيّق item_list أحداث التعليقات؟
تحصر comment.update في المنشورات التي تسمّيها، حتى 100 معرّف من /business/video/list/، ويحدد أول استدعاء قائمة الوضع للتطبيق من تلك اللحظة:
- أول استدعاء COMMENT مع
item_list: تصل الأحداث للمنشورات المدرجة فقط. - الاستدعاءات اللاحقة مع
item_list: تنضم المنشورات الجديدة إلى ما هو مدرج. - استدعاء COMMENT بدون
item_list، ولم يُضبط شيء من قبل: تصل الأحداث لمنشورات الحسابات التي فوّضت التطبيق. - استدعاء COMMENT بدون
item_list، بعد وجود قائمة: تبقى المنشورات المضبوطة كما هي.
كيف تتحقق من الاشتراك أو تزيله؟
يعيد GET إلى /business/webhook/list/ مع app_id وsecret وevent_type الإعداد، فيظهر callback_url فقط إذا وُجد لنوع الحدث ذاك، وitem_list فقط إذا ضُبطت. أما POST إلى /business/webhook/delete/ مع app_id وsecret وevent_type فيزيله؛ وفي حالة COMMENT تزيل item_list في طلب الحذف تلك المنشورات فقط، وبدونها تتوقف أحداث التعليقات لكل المنشورات.
ماذا يجب أن يفعل عنوان URL الخاص بالاستدعاء؟
أن يرد فورا. ترسل TikTok بيانات JSON عبر HTTPS، وتعدّ أي استجابة غير HTTP 200 إرسالا فاشلا، فتعيد المحاولة بتأخير متصاعد أُسّيًا لمدة تصل إلى 72 ساعة قبل حذف الحدث. التسليم مرة واحدة على الأقل، فقد يصل الحدث نفسه مرتين، لذا يجب أن تكون المعالجة آمنة عند التكرار. يحمل كل طلب ثلاث ترويسات تستحق التسجيل: tiktok-signature وwebhook-schema-version وx-tt-logid، ويحمل جسمه client_key وevent وcreate_time بالثواني وuser_openid، وهو business_id الحساب، وcontent، وهو نص JSON متسلسل.
كيف تتحقق من Tiktok-Signature خطوة بخطوة؟
قسّم الترويسة t=<unix>,s=<hex> عند الفواصل، ثم عند علامة المساواة. ابنِ الرسالة الموقّعة من قيمة t ثم نقطة ثم نص الطلب الخام، واحسب عليها HMAC-SHA256 بمفتاح سر التطبيق، ثم رمّزها بالنظام السداسي عشري وقارنها مع s. بعد ذلك تحقق من عمر t، لأن TikTok توقّع وقت الإرسال لمنع إعادة التشغيل، ومثالها الرسمي يقبل تأخيرا قدره 5 ثوان. ويتجنب العمل على نص الطلب الخام كما استُلم إعادة ترميز JSON بشكل مختلف.
import hashlib, hmac, time
def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, s = parts.get("t", ""), parts.get("s", "")
if not t.isdigit():
return False
expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_ageكيف تستقبل أحداث TikTok من خلال easyCoexistence نفسها؟
بإعطاء الحساب وجهة. يحتفظ easyCoexistence بتطبيقه الخاص مشتركا في COMMENT، ويتحقق من توقيع TikTok، ويرد على TikTok فورا، ويرسل كل comment.update لحساب مرتبط إلى نقطة النهاية HTTPS المحددة له. من Claude أو ChatGPT، يأخذ set_social_webhook_destination الحقلين account_id وurl، أو القيمة null للإيقاف، ويعيد سرّ توقيع لا يُعرض إلا مرة واحدة؛ وإعادة استدعائه تُصدر سرًّا جديدًا. أما أحداث النشر فلا تُعاد توجيهها، ويُستخدم get_tiktok_publish_status لمتابعة المنشور بدلا منها.
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
"url": "https://hooks.example.com/tiktok/",
"signing_secret": "whsec_<SECRET>",
"note": "Shown once: store it as a secret. ..."
}كيف تضبطه بواجهة Partner API البرمجية؟
بطلب PUT إلى /channels/{id}/webhook على https://easycoexistence.com/api/v1، مع مفتاح ec_live_ الخاص بك كرمز وصول (token) في ترويسة Bearer، وجسم هو {"url": "https://..."}. تحتوي الاستجابة على webhook_url وsigning_secret وnote، ويوقف {"url": null} إعادة التوجيه. يجب أن يكون العنوان HTTPS على مضيف عام، وتُرجع القناة غير المعروفة الرمز 404 not_found، والمحذوفة 409 removed، والموقوفة 402 suspended على التوالي.
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/tiktok/"}'
{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }كيف يختلف الإرسالان؟
يختلف التوجيه من easyCoexistence عن إرسال TikTok الأصلي في التوقيع والشكل، لذا يحتاج مستقبِل مكتوب لأحدهما إلى تعديلات ليعمل مع الآخر. تحتفظ الحمولة المعاد توجيهها بحقول تعليقات TikTok، مع تحليل content وجعل المعرّفات نصوصا، أما ما يتغير فهو طريقة توقيع كل إرسال وتحديد نطاقه وإعادة محاولته.
| TikTok to your app | easyCoexistence to your endpoint | |
|---|---|---|
| Header | Tiktok-Signature: t=<unix>,s=<hex> | X-EC-Signature: t=<unix>,v1=<hex> |
| Key | The developer app's secret | The account's signing secret, shown once |
| Events | VIDEO and COMMENT, per app | comment.update, per connected account |
| Body | client_key, event, create_time, user_openid, content as a string | platform, account_id, external_id, entry with content parsed |
| Retries | Up to 72 hours | None: one attempt, 8 seconds, no redirects |
كيفية إعداده
- Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
- Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
- Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
- Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
- Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.
الأخطاء الشائعة
- معالجة الحدث قبل الرد. تطلب TikTok رمز 200 فورا وتعيد محاولة الإرسالات التي لم تُقر، لذا ضع العمل في طابور وأرسل الرد أولا.
- إرسال item_list في أول اشتراك COMMENT بالخطأ. منذ ذلك الحين تُبلغ TikTok عن أحداث التعليقات للمنشورات المدرجة فقط.
- التحقق بـ token الوصول بدل سر التطبيق. توقّع TikTok الإرسالات بسر التطبيق نفسه الذي يأخذه /business/webhook/update/.
- توجيه بيئتين إلى تطبيق واحد. لكل نوع حدث عنوان URL واحد لكل تطبيق، وكل استدعاء جديد لـ /business/webhook/update/ يستبدله.
اضبطه بـ set_social_webhook_destination من Claude أو ChatGPT، أو عبر PUT /channels/{id}/webhook. من US$ 9 إلى US$ 0.75 لكل اتصال في الشهر، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
ما الترويسات التي يحملها إرسال webhook من TikTok؟
tiktok-signature وwebhook-schema-version، وقيمتها الحالية v1.0، وx-tt-logid، وهو معرّف الإرسال. ويحتوي جسم JSON على client_key وevent وcreate_time وuser_openid وcontent، وهذه كلها حقول في الجسم.
هل ترسل TikTok webhook عند نشر فيديو؟
نعم، بنوع الحدث VIDEO: يصل post.publish.complete بعد أن تنزّل TikTok الملف وتتحقق منه، ثم post.publish.publicly_available مع post_id حين يصبح المنشور متاحا للعامة.
كم مدة إعادة TikTok محاولة webhook فاشل؟
حتى 72 ساعة مع تأخير متصاعد أُسّيًا، ثم يُحذف الحدث. التسليم مرة واحدة على الأقل، فتوقع التكرار.
هل يمكنني تسجيل عنوان URL خاص بي على تطبيق TikTok التابع لـ easyCoexistence نفسه؟
لا. تبقى إعدادات webhook لتطبيق easyCoexistence عنده. أما set_social_webhook_destination فيرسل إليك أحداث التعليقات الخاصة بالحساب بدلا من ذلك.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في