التحقق من خطاف الويب (webhook) في TikTok: ترويسة التوقيع وطريقة فحصها
توقّع TikTok كل تسليم webhook في ترويسة 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.js لدى TikTok، وهو يرفض تسليمًا موقّعًا بشكل صحيح أقدم منه.
الترويسة التي تحمل المعرّف الفريد لكل تسليم، ويطلب TikTok من المستلمين تسجيله لاستكشاف الأخطاء وإصلاحها.
نوع الحدث لـ webhooks الإشارات، التي تشير صفحة اشتراكها إلى التحقق من التوقيع نفسه.
جزء التوقيع في ترويسة 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.js بناء هذه النسخة بتشغيل JSON.stringify على كائن حُلِّل مسبقًا. وهذا لا يعيد بايتات TikTok إلا إذا اتفق المُسلسِلان في المسافات وترتيب المفاتيح والترميز، لذا قم بتجزئة الجسم كما وصل تمامًا، قبل أن تقرأه أي وسيطة JSON.
ما السر الذي يُستخدم مفتاحًا؟
سر تطبيق المطوّر، ويوجد تحت My Apps وApp Detail وBasic Information في بوابة المطوّرين لدى TikTok. وهو القيمة التي يرسلها التطبيق أصلًا باسم secret إلى /business/webhook/update/ وباسم client_secret إلى نقاط الرموز. سر واحد يوقّع التسليمات لكل حساب فوّض التطبيق، فلا يحتاج المستلم إلى مفتاح لكل حساب، ولا يدخل في الحساب رمز الوصول ولا معرّف التطبيق.
كيف تفحصه في Node.js؟
باستخدام 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.js لديه بـ 5 ثوانٍ، وهي ضيقة بما يكفي لأن يرفض خادم ساعته متأخرة بضع ثوانٍ تسليمات صحيحة. أما الكود أعلاه فيسمح بـ 300، وهي النافذة التي يطلب easyCoexistence من المستلمين استخدامها على إعادات توجيهه الخاصة. احسب العمر من t، وهو وقت التسليم الذي يغطيه التوقيع، لا من create_time في الجسم الذي يحدد وقت وقوع الحدث. في عينة TikTok يقع t بعد create_time بثانية واحدة.
ماذا يجب أن تردّ به نقطة النهاية (endpoint)؟
الرمز 200 فور نجاح التحقق من التوقيع، مع إنجاز العمل لاحقًا، لأن TikTok يعامل أي حالة أخرى كتسليم فاشل ويعيد إرساله. أما التوقيع غير المطابق فترد عليه عينة TikTok برمز 4xx وتسجّل ترويسة x-tt-logid، وهي تعرّف الطلب إذا أبلغت TikTok بمشكلة. يسمي client_key في الجسم تطبيق المطوّر، فمقارنته بمعرّف تطبيقك خطوة ثانية رخيصة.
كيف يُسجَّل عنوان URL للاستدعاء، وهل يُتحقَّق منه؟
بنداء واجهة برمجة التطبيقات (API) واحد، ولا يوثّق TikTok أي طلب تحدٍّ يختبر العنوان أولًا. يقبل POST /business/webhook/update/ المعاملات app_id والسر وevent_type وcallback_url بصيغة HTTPS: القيمة VIDEO لأحداث النشر، والقيمة COMMENT لـ comment.update، والقيمة BRAND_MENTION لـ brand.mention.event في Mentions API. تصل الأنواع الثلاثة موقّعة بالطريقة نفسها، ويعرض GET /business/webhook/list/ العنوان المسجّل لكل نوع حدث. دليل المصدر هو التوقيع على كل تسليم.
هل يمكنك فحص Tiktok-Signature على الأحداث التي تعيد easyCoexistence إرسالها؟
لا، ولا يتطلب الأمر ذلك. يوقّع TikTok تلك التسليمات بسر تطبيق easyCoexistence الخاص بالمطوّر، وهو سر لا تسلّمه أي أداة أو واجهة. يتحقق 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 مرة أخرى إلى إرجاع سر جديد وإبطال القديم فورًا، ولا تُرسل كل إعادة توجيه إلا مرة واحدة، لذا يضيع أي حدث يرفضه خادمك أثناء التبديل. اقبل السرّين معًا لبضع دقائق أثناء نشر الجديد. أما أحداث الحالة المتعلقة بالقنوات والمنشورات فتستخدم سرًا آخر، هو المعروض في لوحة التحكم ← Profile ← Developers، وتصل مع الترويستين X-EC-Event وX-EC-Delivery، وتُعاد محاولتها لنحو 33 ساعة.
الأخطاء الشائعة
- التحقق من جسم حلّله الإطار مسبقًا. يسلّم وسيط JSON كائنًا، وإعادة تسلسله قد تغيّر بايتات TikTok، لذا اقرأ النص الخام على مسار الـ webhook.
- الرد بـ 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 في webhook من TikTok؟
ترويسة تحمل المعرّف الفريد لكل تسليم. يطلب TikTok من المستلمين تسجيلها، لأنها تعرّف الطلب عند الإبلاغ عن مشكلة لدى TikTok.
هل يرسل TikTok تحدٍّ للتحقق من عنوان webhook جديد؟
لا يوثّق TikTok أي تحدٍّ لواجهته API for Business. يسجّل استدعاء /business/webhook/update/ العنوان، ثم تصل التسليمات بترويسة Tiktok-Signature ليفحصها خادمك.
لماذا لا يطابق توقيع webhook في TikTok أبدًا؟
افحص المدخلات والمفتاح: يجب أن تغطي HMAC القيمة t والنقطة والنص الخام كما وصل، وأن تستخدم سر التطبيق، وأن تُقارن بالقيمة بعد s= لا بالترويسة كاملة.
كيف أتحقق من أحداث TikTok التي تعيد easyCoexistence إرسالها؟
بترويسة X-EC-Signature وسر التوقيع الذي عرضته عند ضبط الوجهة: احسب HMAC-SHA256 على t والنقطة والنص الخام، وقارنه بـ v1، وارفض أي t أقدم من 5 دقائق.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في