TikTok ওয়েবহুক যাচাই করা: স্বাক্ষর হেডার ও তা পরীক্ষার উপায়
TikTok-এর API for Business প্রতিটি ওয়েবহুক ডেলিভারিতে একটি Tiktok-Signature হেডারে স্বাক্ষর করে, যার আকার t=<unix seconds>,s=<hex>। এখানে s হলো t-এর মান, একটি ডট এবং রিকোয়েস্ট বডির উপর HMAC-SHA256, যা ডেভেলপার অ্যাপের সিক্রেট দিয়ে তৈরি হয়। যাচাই করতে যেভাবে এসেছে সেই কাঁচা বডির উপর ওই HMAC আবার হিসাব করুন, s-এর সঙ্গে ধ্রুবক-সময়ের তুলনা করুন এবং পুরনো t প্রত্যাখ্যান করুন।
easyCoexistence তার অ্যাপ যে প্রতিটি কমেন্ট ইভেন্ট পায়, সেটিতে TikTok-এর স্বাক্ষর যাচাই করে, তারপর সংযুক্ত অ্যাকাউন্টের কমেন্ট ইভেন্টগুলো আপনার HTTPS এন্ডপয়েন্টে ফরওয়ার্ড করে, X-EC-Signature-এ শুধু সেই অ্যাকাউন্টের সিক্রেট দিয়ে স্বাক্ষরিত।
Tiktok-Signature-এর দুটি অংশ: ডেলিভারির Unix টাইমস্ট্যাম্প সেকেন্ডে এবং TikTok-এর তৈরি করা স্বাক্ষর।
TikTok-এর Node নমুনায় acceptableDelay আছে, যে ডেলিভারি এর চেয়ে পুরনো, সেটি সঠিকভাবে স্বাক্ষরিত হলেও প্রত্যাখ্যান করে।
এমন হেডার যেখানে প্রতিটি ডেলিভারির অনন্য ID থাকে, যা TikTok সমস্যা নিষ্পত্তির জন্য রিসিভারদের লগ রাখতে বলে।
মেনশন ওয়েবহুকের ইভেন্ট টাইপ, যার সাবস্ক্রিপশন গাইড একই স্বাক্ষর যাচাইয়ের দিকে নির্দেশ করে।
easyCoexistence-এর X-EC-Signature হেডারের স্বাক্ষর অংশ, t-এর HMAC-SHA256, একটি ডট এবং কাঁচা বডি।
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: 202201120803530102451591650189C78TikTok কোন বাইটগুলো স্বাক্ষর করে?
t-এর মানটি স্ট্রিং হিসেবে, একটি ডট, তারপর বডি। TikTok-এর গাইড শেষের অংশটিকে রিকোয়েস্ট বডির স্ট্রিংকৃত JSON কপি বলে, এবং এর Node নমুনা একটি আগে থেকে পার্স করা অবজেক্টের উপর JSON.stringify চালিয়ে কপিটি পুনর্গঠন করে। এটি TikTok-এর বাইট শুধু তখনই মেলায় যখন উভয় সিরিয়ালাইজার ফাঁক, কী-এর ক্রম ও এস্কেপিংয়ে একমত হয়; তাই বডি ঠিক যেভাবে এসেছে তেমনই হ্যাশ করুন, কোনো JSON মিডলওয়্যার পড়ার আগে।
কোন সিক্রেট চাবি হিসেবে কাজ করে?
ডেভেলপার অ্যাপের সিক্রেট, যা TikTok-এর ডেভেলপার পোর্টালে My Apps, App Detail, Basic Information-এর নিচে পাওয়া যায়। অ্যাপটি /business/webhook/update/-এ secret হিসেবে এবং টোকেন এন্ডপয়েন্টে client_secret হিসেবে যে মানটি আগে থেকেই পাঠায়, এটি সেই মান। অ্যাপ যেসব অ্যাকাউন্ট অনুমোদন করেছে, প্রতিটির ডেলিভারি একটিমাত্র সিক্রেট দিয়ে স্বাক্ষরিত হয়, তাই রিসিভারের প্রতি অ্যাকাউন্টের জন্য আলাদা কী লাগে না, এবং অ্যাক্সেস টোকেন বা অ্যাপ ID এতে অংশ নেয় না।
Node.js-এ কীভাবে যাচাই করবেন?
node:crypto ও কাঁচা বডি দিয়ে। নিচের ফাংশনটি হেডার ভাগ করে, t, ডট ও বডির বাইট দিয়ে HMAC আবার হিসাব করে, ফলাফল ধ্রুবক-সময়ে তুলনা করে, তারপর 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, create_time-এর এক সেকেন্ড পরে পড়ে।
এন্ডপয়েন্টের কী উত্তর দেওয়া উচিত?
স্বাক্ষর মিললেই 200 দিন, কাজটি পরে করে। কারণ TikTok অন্য যেকোনো স্ট্যাটাসকে ব্যর্থ ডেলিভারি ধরে আবার পাঠায়। যে স্বাক্ষর মেলে না, তার জন্য TikTok-এর নমুনা একটি 4xx স্ট্যাটাস দেয় এবং x-tt-logid হেডার লগ করে, যা TikTok-কে সমস্যা জানালে রিকোয়েস্টটি চিহ্নিত করে। বডির client_key ডেভেলপার অ্যাপের নাম দেয়, তাই এটি আপনার নিজের অ্যাপ ID-এর সঙ্গে মেলানো একটি সহজ দ্বিতীয় পরীক্ষা।
Callback URL কীভাবে নিবন্ধন হয়, এবং তা কি যাচাই হয়?
একটি API কলে, এবং TikTok নতুন URL পরীক্ষা করার জন্য কোনো চ্যালেঞ্জ রিকোয়েস্ট নথিভুক্ত করে না। POST /business/webhook/update/ নেয় app_id, secret, একটি event_type এবং একটি HTTPS callback_url: পাবলিশিং ইভেন্টের জন্য VIDEO, comment.update-এর জন্য COMMENT এবং Mentions API-তে brand.mention.event-এর জন্য BRAND_MENTION। তিনটিই একইভাবে স্বাক্ষরিত হয়ে আসে, এবং GET /business/webhook/list/ একটি ইভেন্ট টাইপের জন্য নিবন্ধিত URL দেখায়। উৎসের প্রমাণ হলো প্রতিটি ডেলিভারির স্বাক্ষর।
easyCoexistence যে ইভেন্টগুলো ফরওয়ার্ড করে, সেগুলোতে কি Tiktok-Signature যাচাই করা যায়?
না, এবং এর প্রয়োজনও নেই। TikTok ওই ডেলিভারিগুলো easyCoexistence-এর নিজের ডেভেলপার অ্যাপের সিক্রেট দিয়ে স্বাক্ষর করে, যা কোনো টুল বা API দেয় না। easyCoexistence প্রতিটি ইভেন্ট আসার সময় ওই স্বাক্ষর যাচাই করে, ব্যর্থ হলে 401 দেয়, এমন বডি উপেক্ষা করে যার client_key অন্য অ্যাপের নাম দেয়, এবং তারপর আপনার কাছে ফরওয়ার্ড করার সময় সংযুক্ত সেই অ্যাকাউন্টের সাইনিং সিক্রেট দিয়ে X-EC-Signature-এ স্বাক্ষর করে।
easyCoexistence তার ফরওয়ার্ড কীভাবে স্বাক্ষর করে?
X-EC-Signature হেডারে, t=<unix>,v1=<hex> ফরমে, যেখানে t হলো ফরওয়ার্ডের সময় এবং v1 হলো t, একটি ডট ও ঠিক যেভাবে পাঠানো হয়েছে সেই বডির hex HMAC-SHA256। কী হলো অ্যাকাউন্টের সাইনিং সিক্রেট, যা 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-এর বাইট বদলে যেতে পারে; ওয়েবহুক রুটে কাঁচা বডি পড়ুন।
- স্বাক্ষর ব্যর্থ হওয়া ডেলিভারিতে 200 দেওয়া। TikTok একবার 200 দেখলে একটি ইভেন্ট পাঠানো বন্ধ করে, তাই ভুল কনফিগার করা যাচাইয়ের কারণে প্রত্যাখ্যাত বৈধ ইভেন্ট হারিয়ে যায়; 4xx দিলে TikTok 72 ঘণ্টা পর্যন্ত পুনরায় চেষ্টা করতে থাকে।
- === দিয়ে স্বাক্ষর তুলনা করা, যেমন TikTok-এর নমুনায় আছে। ধ্রুবক-সময়ের তুলনা, যেমন timingSafeEqual, জাল স্বাক্ষরের কতটুকু মিলেছে তা প্রকাশ করে না।
- easyCoexistence-এর সিক্রেট Base64-ডিকোড করা বা তার whsec_ উপসর্গ কেটে ফেলা। HMAC-এর কী হলো পুরো স্ট্রিংটি, ঠিক যেভাবে একবার দেখানো হয়েছিল।
Claude বা ChatGPT থেকে set_social_webhook_destination দিয়ে, অথবা PUT /channels/{id}/webhook দিয়ে এন্ডপয়েন্ট সেট করুন। প্রতি সংযোগে প্রতি মাসে US$ 9 থেকে US$ 0.75, সংযোগ বাড়ালে কমে, প্রথম 3 দিন ফ্রি ট্রায়াল।
প্রায়শই জিজ্ঞাসিত প্রশ্ন
TikTok ওয়েবহুকে x-tt-logid কী?
প্রতিটি ডেলিভারির একটি অনন্য ID বহনকারী হেডার। TikTok রিসিভারদের এটি লগ করতে বলে, কারণ TikTok-কে সমস্যা জানানোর সময় এটি রিকোয়েস্ট চিহ্নিত করে।
TikTok কি নতুন ওয়েবহুক URL যাচাই করতে চ্যালেঞ্জ পাঠায়?
TikTok তার API for Business-এর জন্য কোনোটিই নথিভুক্ত করে না। /business/webhook/update/ কল URL নিবন্ধন করে, এবং তারপর ডেলিভারি আসে Tiktok-Signature সহ, যাতে আপনার সার্ভার সেটি যাচাই করতে পারে।
কেন আমার TikTok ওয়েবহুক স্বাক্ষর কখনো মেলে না?
ইনপুট ও কী পরীক্ষা করুন: HMAC-কে অবশ্যই t, একটি ডট এবং যেভাবে এসেছে সেই কাঁচা বডি ঢাকতে হবে, অ্যাপের সিক্রেট ব্যবহার করতে হবে, এবং পুরো হেডারের বদলে s= এর পরের মানের সঙ্গে তুলনা করতে হবে।
easyCoexistence-এর ফরওয়ার্ড করা TikTok ইভেন্ট কীভাবে যাচাই করব?
X-EC-Signature ও ডেস্টিনেশন সেট করার সময় দেখানো স্বাক্ষর সিক্রেট দিয়ে: t, একটি ডট ও কাঁচা বডির উপর HMAC-SHA256 আবার হিসাব করুন, v1-এর সঙ্গে তুলনা করুন, এবং 5 মিনিটের বেশি পুরনো t প্রত্যাখ্যান করুন।
আরও পড়ুন
দুই মিনিটে আপনার প্রথম চ্যানেল সংযুক্ত করুন।
প্ল্যাটফর্মের রিভিউয়ের জন্য অপেক্ষা করতে হবে না। WhatsApp, Instagram, TikTok বা অন্য কোনো চ্যানেল সংযুক্ত করুন, তারপর আপনার AI-কে পোস্ট করতে, রিপ্লাই দিতে বা রিপোর্ট দিতে বলুন, আর নিজের চোখে দেখুন কীভাবে কাজ করে।
- 3 দিন ফ্রি
- যেকোনো সময় বাতিল করুন
- শুধুমাত্র অফিশিয়াল API
- 24/7 পর্যবেক্ষণ
যাচাই করা হয়েছে