אימות וובהוקים (Webhook) של TikTok: כותרת החתימה ואיך בודקים אותה
TikTok API for Business חותם כל משלוח וובהוק בכותרת Tiktok-Signature בצורה t=<unix seconds>,s=<hex>, כאשר s הוא ה-HMAC-SHA256 של הערך t, נקודה וגוף הבקשה, עם סוד אפליקציית המפתחים. כדי לאמת משלוח, מחשבים מחדש את ה-HMAC על הגוף הגולמי כפי שהתקבל, משווים אותו ל-s בהשוואה בזמן קבוע, ודוחים t ישן.
easyCoexistence בודק את חתימת TikTok בכל אירוע תגובה שהאפליקציה שלו מקבלת, ואז מעביר את אירועי התגובות של החשבון המחובר לנקודת הקצה ה-HTTPS שלכם, חתומים ב-X-EC-Signature עם סוד שמיועד לחשבון הזה בלבד.
שני חלקי Tiktok-Signature: חותמת הזמן של המשלוח ב-Unix בשניות והחתימה ש-TikTok יצר עבורו.
השדה acceptableDelay בדוגמת Node של TikTok, שדוחה משלוח שנחתם כהלכה אם הוא ישן ממנו.
הכותרת שנושאת מזהה ייחודי לכל משלוח, ש-TikTok מבקש מהמקבלים לרשום ביומן לצורך פתרון תקלות.
סוג האירוע של וובהוקי האזכורים, שמדריך המינוי שלהם מפנה לאותו אימות חתימה.
חלק החתימה בכותרת X-EC-Signature של easyCoexistence, ה-HMAC-SHA256 של t, נקודה והגוף הגולמי.
איך נראית כותרת Tiktok-Signature?
שני חלקים מופרדים בפסיק: t, חותמת הזמן של אותו משלוח ביחידות Unix בשניות, ו-s, החתימה, באורך של 64 תווים הקסדצימליים. דפי TikTok כותבים את השם כ-TikTok-Signature, Tiktok-Signature וגם tiktok-signature. שמות כותרות HTTP אינם רגישים לאותיות גדולות וקטנות, לכן קראו אותו ללא התחשבות באותיות, כפי שרוב המסגרות עושות כבר. מופיעות במשלוח הדוגמה של TikTok הכותרות הבאות:
content-type: application/json;charset=UTF-8
user-agent: tiktok-webhook
tiktok-signature: t=1641974633,s=dc023ece112b3a07d809896fd929928a132168d95d2a2e43aab0105fbb291df8
webhook-schema-version: v1.0
x-tt-logid: 202201120803530102451591650189C78אילו בייטים TikTok חותם עליהם?
המחרוזת של הערך t, נקודה, ואז הגוף. המדריך של TikTok מכנה את החלק האחרון עותק מומר ל-JSON של גוף הבקשה, ודוגמת ה-Node שלו בונה את העותק מחדש על ידי הרצת JSON.stringify על אובייקט שכבר פורסר. כך מתקבלים הבייטים של TikTok רק כששני המסדרים מסכימים על הרווחים, סדר המפתחות וה-escaping, ולכן יש לחשב HMAC על הגוף בדיוק כפי שהגיע, לפני שכל middleware של JSON קורא אותו.
איזה סוד הוא המפתח?
סוד האפליקציה של המפתחים, שנמצא תחת My Apps, App Detail, Basic Information בפורטל המפתחים של TikTok. זהו הערך שהאפליקציה כבר שולחת כ-secret אל /business/webhook/update/ וכ-client_secret אל נקודות הקצה של האסימון. סוד אחד חותם את המשלוחים לכל חשבון שאישר את האפליקציה, ולכן המקבל אינו דורש מפתח לכל חשבון, ולא אסימון הגישה ולא מזהה האפליקציה משתתפים בחתימה.
איך בודקים את החתימה בקוד?
עם node:crypto והגוף הגולמי. הפונקציה שלהלן מפצלת את הכותרת, מחשבת מחדש את ה-HMAC על הבייטים של t, נקודה והגוף, משווה את התוצאה בזמן קבוע ואז בודקת את גיל ה-t. היא מקבלת כארגומנט את שם חלק החתימה, כך שאותו קוד בודק גם את ההעברות של easyCoexistence, שם החלק נקרא v1 והמפתח הוא סוד החתימה של החשבון:
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
// Tiktok-Signature reads t=<unix>,s=<hex>; X-EC-Signature reads t=<unix>,v1=<hex>.
function verifySignature(rawBody, header, secret, name, maxAgeSeconds = 300) {
const parts = {};
for (const item of String(header ?? "").split(",")) {
const i = item.indexOf("=");
if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
}
const signature = parts[name];
if (!/^\d+$/.test(parts.t ?? "") || !signature) return false;
const expected = createHmac("sha256", secret)
.update(parts.t + ".")
.update(rawBody) // the bytes exactly as they arrived
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
return Math.abs(Date.now() / 1000 - Number(parts.t)) <= maxAgeSeconds;
}
const app = express();
// TikTok to your own developer app: the app secret, part s
app.post("/webhooks/tiktok", express.raw({ type: "application/json" }), (req, res) => {
if (!verifySignature(req.body, req.get("tiktok-signature"), process.env.TIKTOK_APP_SECRET, "s")) {
console.warn("TikTok signature rejected, x-tt-logid:", req.get("x-tt-logid"));
return res.sendStatus(401);
}
res.sendStatus(200); // acknowledge first: TikTok retries anything but a 200
enqueue(req.body.toString("utf8")); // its content field is itself a JSON string
});
// easyCoexistence to your endpoint: the account's whsec_ secret, part v1
app.post("/webhooks/easycoexistence", express.raw({ type: "application/json" }), (req, res) => {
if (!verifySignature(req.body, req.get("x-ec-signature"), process.env.EC_SIGNING_SECRET, "v1")) {
return res.sendStatus(401);
}
res.sendStatus(200);
enqueue(req.body.toString("utf8")); // platform, account_id, external_id, entry
});כמה ישן יכול להיות משלוח לפני שדוחים אותו?
TikTok משאיר את גבול הזמן למקבל: לחשב את הפער בין השעון שלכם לבין t, כפי שכתוב במדריך, ולהחליט אם הוא מקובל. דוגמת ה-Node שלו מתירה 5 שניות, חלון צר כל כך שלשרת שהשעון שלו סוטה בכמה שניות עלול לדחות משלוחים אמיתיים. הקוד שלמעלה מתיר 300, החלון ש-easyCoexistence מבקש מהמקבלים להשתמש בו בהעברות שלה. מודדים מ-t, זמן המשלוח שהחתימה מכסה, ולא מהשדה create_time בגוף, שמסמן מתי התרחש האירוע. בדוגמה של TikTok, t מאוחר בשנייה אחת מזמן היצירה שבגוף.
מה נקודת הקצה צריכה להחזיר?
200 מיד כשהחתימה נבדקה והיא תקינה, והעבודה נעשית אחר כך, כי TikTok מתייחס לכל סטטוס אחר ככישלון במשלוח ושולח אותו שוב. לחתימה שאינה תואמת, הדוגמה של TikTok עונה בסטטוס 4xx ומתעדת את הכותרת x-tt-logid, שמזהה את הבקשה אם מדווחים על תקלה ל-TikTok. הערך client_key בגוף מציין את אפליקציית המפתחים, ולכן השוואה שלו עם מזהה האפליקציה שלכם היא בדיקה שנייה זולה.
איך נרשמת כתובת ה-callback, והאם היא מאומתת?
בקריאת API אחת, וTikTok אינו מתעד בקשת אתגר שבודקת את הכתובת קודם. POST /business/webhook/update/ מקבל את השדות app_id ו-secret, את event_type ואת callback_url ב-HTTPS: VIDEO לאירועי פרסום, COMMENT ל-comment.update, ובממשק Mentions API גם BRAND_MENTION ל-brand.mention.event. כולם מגיעים חתומים באותה דרך, ו-GET /business/webhook/list/ מציג את הכתובת הרשומה לכל סוג אירוע. הוכחת המקור היא החתימה בכל משלוח.
האם אפשר לבדוק את Tiktok-Signature באירועים שש-easyCoexistence מעביר?
לא, ואין צורך בכך. TikTok חותם את המשלוחים האלה עם הסוד של אפליקציית המפתחים של easyCoexistence עצמה, שאף כלי או API אינו מוסר. easyCoexistence בודק את החתימה הזאת כשכל אירוע מגיע, עונה 401 לאירוע שנכשל, מתעלם מגוף שבו client_key מציין אפליקציה אחרת, ואז חותם את ההעברה אליכם ב-X-EC-Signature עם סוד החתימה של אותו חשבון מחובר.
איך easyCoexistence חותם את מה שהוא מעביר?
בכותרת X-EC-Signature, t=<unix>,v1=<hex>, כאשר t הוא זמן ההעברה ו-v1 הוא ה-HMAC-SHA256 בהקסדצימלי של t, נקודה והגוף בדיוק כפי שנשלח. המפתח הוא סוד החתימה של החשבון, whsec_ ואחריו 32 תווים, בשימוש מלא כולל הקידומת. מבין הכותרות שלו, easyCoexistence שולח רק את Content-Type והכותרת הזאת, בלי כותרת אירוע, לכן יש לקרוא את שם האירוע מהמטען, מתוך השדה entry.event, כפי שמוצג להלן:
POST https://hooks.example.com/tiktok/
Content-Type: application/json
X-EC-Signature: t=1793318405,v1=<HMAC_SHA256_HEX>
{"platform":"tiktok","account_id":"<ACCOUNT_ID>","external_id":"<TIKTOK_OPEN_ID>","entry":{"event":"comment.update","create_time":1793318400,"content":{...}}}
v1 = hex(HMAC-SHA256(key = "whsec_<SECRET>", message = "1793318405." + raw body))מה קורה כשסוד החתימה מוחלף?
הסוד החדש חותם מההעברה הבאה והלאה. קריאה לכלי set_social_webhook_destination או ל-PUT /channels/{id}/webhook שוב מחזירה סוד חדש ומבטלת את הישן מיד, וכל העברה נשלחת פעם אחת בלבד, כך שאירוע שהשרת דוחה בזמן המעבר הולך לאיבוד. בזמן פריסת החדש מקבלים את שני הסודות למשך כמה דקות. לאירועי סטטוס על חשבונות ופוסטים יש סוד אחר, הנמצא תחת Dashboard, Profile, Developers, והם מגיעים עם הכותרות X-EC-Event ו-X-EC-Delivery ונשלחים שוב במשך כ-33 שעות.
טעויות נפוצות
- אימות גוף שכבר פורסר על ידי הפריימוורק. middleware של JSON מעביר אובייקט, וסריאליזציה שלו מחדש עלולה לשנות את הבייטים של TikTok; יש לקרוא את הגוף הגולמי בנתיב הוובהוק.
- החזרת 200 למשלוח שהחתימה שלו נכשלה. TikTok מפסיק לשלוח אירוע ברגע שהוא מקבל 200, ולכן משלוח אמיתי שנדחה בגלל בדיקה שגויה הולך לאיבוד; סטטוס 4xx גורם ל-TikTok לנסות שוב במשך עד 72 שעות.
- השוואת חתימות באמצעות ===, כפי שעושה הדוגמה של TikTok. השוואה בזמן קבוע, כמו timingSafeEqual, אינה חושפת כמה מחתימה מזויפת התאימה.
- פענוח Base64 של הסוד של easyCoexistence, או קיצוץ הקידומת whsec_ שלו. מפתח ה-HMAC הוא המחרוזת כולה, בדיוק כפי שהוצגה פעם אחת.
נקודת הקצה נקבעת עם set_social_webhook_destination מ-Claude או מ-ChatGPT, או עם PUT /channels/{id}/webhook. US$ 9 עד US$ 0.75 לחיבור לחודש, יורד ככל שמוסיפים חיבורים, כולל תקופת ניסיון של 3 ימים בחינם.
שאלות נפוצות
מה תפקיד הכותרת x-tt-logid בוובהוק?
כותרת שנושאת מזהה ייחודי לכל משלוח. TikTok מבקש מהמקבלים לרשום אותו ביומן, כי הוא מזהה את הבקשה כשמדווחים על תקלה ל-TikTok.
האם TikTok שולח אתגר כדי לאמת כתובת וובהוק חדשה?
TikTok אינו מתעד אתגר כזה ב-API for Business שלו. הקריאה ל-/business/webhook/update/ רושמת את הכתובת, ואז המשלוחים מגיעים עם Tiktok-Signature כדי שהשרת שלכם יבדוק אותם.
למה חתימת הוובהוק של TikTok שלי לעולם לא תואמת?
בודקים את הקלט והמפתח: ה-HMAC חייב לכסות את t, נקודה והגוף הגולמי כפי שהתקבל, להשתמש בסוד האפליקציה, ולהשוות לערך שאחרי s= ולא לכותרת כולה.
איך מאמתים את אירועי TikTok שעברו דרך easyCoexistence, ומה נדרש?
בעזרת X-EC-Signature וסוד החתימה שמוצג כשקובעים את היעד: מחשבים מחדש את ה-HMAC-SHA256 על t, נקודה והגוף הגולמי, משווים לערך v1, ודוחים כל t שישן מחמש דקות.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-