הגדרת וובהוקים ל-TikTok API for Business
השירות של TikTok לעסקים שולח וובהוקים (Webhooks) לכתובת callback אחת לכל אפליקציית מפתחים ולכל סוג אירוע, שמוגדרת באמצעות POST /business/webhook/update/ עם app_id וסוד האפליקציה. הסוג VIDEO רושם את ארבעת אירועי פרסום הפוסטים, והסוג COMMENT רושם את האירוע comment.update. כל משלוח הוא בקשת HTTPS מסוג POST, שנחתמת בכותרת Tiktok-Signature באמצעות HMAC-SHA256 עם מפתח סוד האפליקציה.
easyCoexistence שומרת את האפליקציה שלה רשומה לאירועי התגובות של TikTok, בודקת את חתימת TikTok ומעבירה כל אירוע תגובה לחשבון שלכם אל נקודת הקצה ב-HTTPS שלכם, חתום במפתח סוד משלה.
כמה זמן TikTok מנסה שוב משלוח שלא קיבל תשובה HTTP 200, עם המתנה מעריכית הולכת וגדלה, לפני שהוא זורק אותו.
המספר המרבי של מזהי פוסטים שאפשר לכלול בשדה item_list כדי להגביל את אירועי comment.update לפוסטים מסוימים.
הערך הנוכחי של הכותרת webhook-schema-version ש-TikTok שולח עם כל משלוח.
מה מפרט מסמך הייחוס של TikTok עבור נקודות הקצה להגדרת וובהוקים, שמאמתות באמצעות app ID והסוד.
אלגוריתם החתימה של Tiktok-Signature: חותמת הזמן, נקודה וגוף הבקשה, נחתמים במפתח הסוד ומקודדים ב-hex.
הרשאה של האפליקציה תחת TikTok Accounts הנדרשת לאירוע comment.update; אירועי הפרסום דורשים את ההרשאה Business Content.
אילו אירועי וובהוק יכולה לקבל אפליקציה לחשבון TikTok?
שתי קטגוריות, שכל אחת נרשמת כסוג event_type נפרד. VIDEO מכסה פוסטים שפורסמו דרך /business/video/publish/ או /business/photo/publish/, ו-COMMENT מכסה תגובות לפוסטים של תמונות ולסרטונים ציבוריים של החשבון, בין אם פורסמו דרך ה-API ובין אם באפליקציית TikTok:
מה האפליקציה צריכה לפני הרישום?
גישה ל-API for Business, אפליקציית מפתחים וחשבונות TikTok שאישרו אותה. מדריך הרישום של TikTok מוסיף הרשאה לכל קטגוריה, ולאירוע התגובות נדרש היקף הרשאה מכל בעלים:
- אירועי פרסום: ההרשאה TikTok Accounts, Business Content באפליקציה.
- אירועי תגובות: ההרשאה TikTok Accounts, Business Comment באפליקציה.
- comment.update: ההיקף comment.list, שהבעלים מעניק ושומר בתוקף.
- כתובת callback מסוג HTTPS שעונה HTTP 200 מיד.
איך נרשמים?
עם POST אל /business/webhook/update/, פעם אחת לכל event_type. הגוף מכיל את app_id וסוד האפליקציה, את event_type, שהוא VIDEO או COMMENT, ואת callback_url; עבור COMMENT אפשר להוסיף גם item_list. התשובה משקפת את app_id, event_type ו-callback_url, וכן item_list אם הוגדר. קריאה נוספת לאותו event_type מחליפה את כתובת ה-callback.
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, סוד האפליקציה, event_type מחזיר את ההגדרה: callback_url מופיע רק כשקיימת כתובת לסוג האירוע, ו-item_list רק כשהוגדר. POST אל /business/webhook/delete/ עם השדות app_id, סוד האפליקציה, event_type מסיר אותו; עבור COMMENT, item_list בקריאת המחיקה מסיר רק את הפוסטים האלה, ובלעדיו אירועי התגובות מפסיקים לכל הפוסטים.
מה כתובת ה-callback חייבת לעשות?
לענות מיד. 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 שלה עם מפתח הסוד של האפליקציה, מקודדים ב-hex ומשווים לערך 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_ כאסימון 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 עצמו, לכן מקבל שנכתב לאחד מהם צריך שינויים כדי לתמוך בשני. ה-payload המועבר שומר על שדות התגובה של 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 מבקש HTTP 200 מיד ומנסה שוב משלוחים שלא קיבל עליהם אישור, לכן שימו את העבודה בתור והשיבו קודם.
- שליחת item_list בהרשמת COMMENT הראשונה בטעות. מאותו רגע TikTok מדווח אירועי תגובות לפוסטים שברשימה בלבד.
- אימות עם אסימון הגישה. TikTok חותם את הוובהוקים עם סוד האפליקציה, אותו סוד שנדרש בקריאה אל /business/webhook/update/.
- הפניית שתי סביבות לאותה אפליקציה. כל סוג אירוע שומר כתובת callback אחת לכל אפליקציה, וקריאה חדשה אל /business/webhook/update/ מחליפה אותה.
מגדירים את היעד עם set_social_webhook_destination מ-Claude או מ-ChatGPT, או עם PUT /channels/{id}/webhook. מ-US$ 9 ועד US$ 0.75 לחיבור בחודש, יורד ככל שמוסיפים חיבורים, כולל תקופת ניסיון של 3 ימים בחינם.
שאלות נפוצות
אילו כותרות נשלחות במשלוח וובהוק של TikTok?
tiktok-signature, webhook-schema-version, כרגע v1.0, ואת x-tt-logid, מזהה המשלוח. גוף ה-JSON מכיל את client_key, event, create_time, user_openid ואת content.
האם TikTok שולח וובהוק כשסרטון מפורסם?
כן, עם event_type VIDEO: post.publish.complete לאחר ש-TikTok הוריד ובדק את הקובץ, ואחריו post.publish.publicly_available, עם post_id, כשהפוסט הופך לציבורי.
כמה זמן TikTok מנסה שוב וובהוק שנכשל?
עד 72 שעות בהמתנה מעריכית, ואחר כך האירוע נזרק. המשלוח הוא לפחות פעם אחת, לכן צפו לכפילויות.
אפשר לרשום כתובת callback משלי באפליקציית TikTok של easyCoexistence?
לא. הגדרות הוובהוקים של האפליקציה נשארות אצל easyCoexistence. במקום זה set_social_webhook_destination שולח אליכם את אירועי התגובות של החשבון.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-