Pag-verify ng TikTok webhooks: ang signature header at kung paano ito suriin
Pinipirmahan ng API for Business ng TikTok ang bawat webhook delivery sa isang Tiktok-Signature header na may format na t=<unix seconds>,s=<hex>, kung saan ang s ay HMAC-SHA256 ng halaga ng t, isang tuldok, at ng request body, gamit ang secret ng developer app. Para i-verify ito, kalkulahin muli ang HMAC sa raw body na natanggap, ihambing ito sa s sa constant time, at tanggihan ang lumang t.
Sinusuri ng easyCoexistence ang signature ng TikTok sa bawat comment event na natatanggap ng app nito, pagkatapos ay ipinapasa ang comment events ng konektadong account sa inyong HTTPS endpoint, pinirmahan sa X-EC-Signature gamit ang secret para sa account na iyon lamang.
Ang dalawang bahagi ng Tiktok-Signature: ang Unix timestamp ng delivery sa segundo at ang signature na ginawa ng TikTok para dito.
Ang acceptableDelay sa Node sample ng TikTok, na tinatanggihan ang delivery na tama ang signature ngunit mas luma kaysa sa halagang iyon.
Header na nagdadala ng unique ID ng bawat delivery, na hinihiling ng TikTok sa mga receiver na i-log para sa troubleshooting.
Event type para sa mention webhooks, na itinuturo ng subscription guide nito sa parehong signature verification.
Ang signature part ng X-EC-Signature header ng easyCoexistence, isang HMAC-SHA256 ng t, tuldok, at ng raw body.
Ano ang itsura ng Tiktok-Signature header?
Dalawang bahagi, pinaghihiwalay ng comma: t, ang Unix timestamp sa segundo ng delivery na iyon, at s, ang signature, na 64 na hexadecimal character ang haba. Iba-iba ang pagsulat ng TikTok sa pangalan: TikTok-Signature, Tiktok-Signature, at tiktok-signature. Hindi sensitibo sa case ang mga HTTP header name, kaya basahin ito nang hindi tinitingnan ang case, gaya ng ginagawa na ng karamihan sa framework. Ang iba pang header sa sample delivery ng 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: 202201120803530102451591650189C78Aling bytes ang pinipirmahan ng TikTok?
Ang halaga ng t bilang string, tuldok, at pagkatapos ang body. Tinatawag ng guide ng TikTok ang huling bahaging iyon na stringified JSON copy ng request body, at muling binubuo ng Node sample nito ang kopya sa pamamagitan ng JSON.stringify sa object na na-parse na. Nagtutugma lang iyon sa bytes ng TikTok kapag pareho ang spacing, key order, at escaping ng dalawang serializer, kaya i-hash ang body eksakto kung paano ito dumating, bago pa basahin ng anumang JSON middleware.
Aling secret ang ginagamit na key?
Ang secret ng developer app, na makikita sa My Apps, App Detail, Basic Information sa developer portal ng TikTok. Ito ang halagang ipinapadala na ng app bilang secret sa /business/webhook/update/ at bilang client_secret sa token endpoints. Iisang secret ang pumipirma sa mga delivery para sa bawat account na nag-authorize sa app, kaya hindi na kailangan ng receiver ng key kada account, at wala ring papel ang access token o app ID.
Paano ito sinusuri sa Node.js?
Gamit ang node:crypto at ang raw body. Hinahati ng function sa ibaba ang header, kinakalkula muli ang HMAC sa t, tuldok, at mga byte ng body, ikinukumpara ang resulta sa constant time, at saka sinusuri ang edad ng t. Tumatanggap ito ng pangalan ng signature part bilang argumento, kaya gumagana rin ang parehong code sa mga forward ng easyCoexistence, kung saan ang bahaging iyon ay tinatawag na v1 at ang key ay ang signing secret ng account:
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
});Gaano kalumang delivery ang tinatanggihan?
Ang TikTok ang nagpapasya ng cut-off para sa receiver: kalkulahin ang agwat ng iyong clock at ng t, ayon sa guide nito, at magpasya kung katanggap-tanggap ito. Pinapayagan ng Node sample nito ang 5 segundo, sapat na masikip para tanggihan ang totoong delivery kapag ilang segundo ang mali ng server clock. Ang code sa itaas ay nagpapahintulot ng 300, ang window na hinihiling ng easyCoexistence sa mga receiver para sa sarili nitong forward. Sukatin mula sa t, ang oras ng delivery na sakop ng signature, hindi mula sa create_time sa body, na nagmamarka kung kailan nangyari ang event. Sa sample ng TikTok, isang segundo pagkatapos ng create_time ang t.
Ano ang dapat isagot ng endpoint?
Isang 200 kapag tama ang signature, at gawin ang trabaho pagkatapos, dahil itinuturing ng TikTok ang anumang ibang status bilang nabigong delivery at ipinapadala itong muli. Para sa signature na hindi tumutugma, sumasagot ang sample ng TikTok ng 4xx status at nilo-log ang x-tt-logid header, na tumutukoy sa request kapag may iniulat na problema sa TikTok. Pinapangalanan ng client_key sa body ang developer app, kaya madaling dagdag na pagsusuri ang pagkukumpara nito sa sarili mong app ID.
Paano nirerehistro ang callback URL, at may verification ba?
Sa pamamagitan ng isang API call, at walang challenge request ang TikTok na sumusubok muna sa URL. Tumatanggap ang POST /business/webhook/update/ ng app_id, ng secret, ng event_type, at ng HTTPS callback_url: VIDEO para sa publishing events, COMMENT para sa comment.update, at BRAND_MENTION para sa brand.mention.event sa Mentions API. Pareho ang pagpirma sa lahat ng tatlo, at ipinapakita ng GET /business/webhook/list/ ang URL na nakarehistro sa bawat event type. Ang patunay ng pinagmulan ay ang signature sa bawat delivery.
Maaari bang suriin ang Tiktok-Signature sa mga event na ipinapasa ng easyCoexistence?
Hindi, at walang dahilan para gawin ito. Pinipirmahan ng TikTok ang mga delivery na iyon gamit ang secret ng sariling developer app ng easyCoexistence, na hindi ibinibigay ng anumang tool o API. Sinusuri ng easyCoexistence ang signature na iyon habang dumarating ang bawat event, sumasagot ng 401 sa hindi tumutugma, nagbabalewala ng body na ang client_key ay pangalan ng ibang app, at saka pinipirmahan ang forward sa inyong endpoint sa X-EC-Signature gamit ang signing secret ng konektadong account na iyon.
Paano pinipirmahan ng easyCoexistence ang ipinapasa nito?
Sa X-EC-Signature header, t=<unix>,v1=<hex>, kung saan ang t ay oras ng forward at ang v1 ay hex HMAC-SHA256 ng t, tuldok, at ng body na eksaktong ipinadala. Ang key ay ang signing secret ng account, na nagsisimula sa whsec_ kasunod ng 32 character, ginagamit nang buo, kasama ang prefix. Sa mga sariling header nito, tanging Content-Type at ang header na ito lang ang itinatakda ng easyCoexistence, walang event header, kaya basahin ang pangalan ng event mula sa 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))Ano ang mangyayari kapag pinalitan ang signing secret?
Ang bagong secret ang pumipirma simula sa susunod na forward. Kapag tinawag muli ang set_social_webhook_destination o PUT /channels/{id}/webhook, nagbibigay ito ng bagong secret at agad na inaalis ang luma, at isang beses lang naipapadala ang bawat forward, kaya nawawala ang event na tinanggihan ng server habang nagpapalit. Tanggapin ang dalawang secret sa loob ng ilang minuto habang nagde-deploy ang bago. Ang status events tungkol sa channels at posts ay gumagamit ng ibang secret, ang makikita sa Dashboard, Profile, Developers, at dumarating na may X-EC-Event at X-EC-Delivery headers, na inuulit nang humigit-kumulang 33 oras.
Mga karaniwang pagkakamali
- Pag-verify sa body na naunang na-parse ng framework. Ibinibigay ng JSON middleware ang object, at ang muling pag-serialize nito ay maaaring magbago sa bytes ng TikTok. Basahin ang raw body sa webhook route.
- Pagsagot ng 200 sa delivery na nabigo ang signature. Itinitigil ng TikTok ang pagpapadala ng event kapag nakakita ito ng 200, kaya nawawala ang totoong event na natanggihan ng maling check; ang 4xx naman ay nagpapatuloy ang pag-retry ng TikTok hanggang 72 oras.
- Pagkukumpara ng signature gamit ang ===, gaya ng sample ng TikTok. Hindi ipinapakita ng constant-time comparison gaya ng timingSafeEqual kung gaano karami ang tumugma sa pekeng signature.
- Pag-base64-decode sa secret ng easyCoexistence o pagputol sa prefix nitong whsec_. Ang HMAC key ay ang buong string, eksaktong ipinakita nang minsan.
Itakda ang endpoint gamit ang set_social_webhook_destination mula sa Claude o ChatGPT, o gamit ang PUT /channels/{id}/webhook. US$ 9 hanggang US$ 0.75 kada koneksyon kada buwan, bumababa habang dumarami ang koneksyon, kasama ang unang 3 araw na free trial.
Mga madalas itanong
Ano ang x-tt-logid sa TikTok webhook?
Isang header na nagdadala ng unique ID ng bawat delivery. Hinihiling ng TikTok sa mga receiver na i-log ito, dahil tinutukoy nito ang request kapag may iniulat na problema sa TikTok.
Nagpapadala ba ang TikTok ng challenge para i-verify ang bagong webhook URL?
Wala itong dokumentado para sa API for Business nito. Ang tawag sa /business/webhook/update/ ang nagrerehistro ng URL, at pagkatapos ay dumarating ang mga delivery na may Tiktok-Signature para suriin ng inyong server.
Bakit hindi kailanman tumutugma ang signature ng TikTok webhook ko?
Suriin ang input at ang key: dapat sakupin ng HMAC ang t, tuldok, at raw body na dumating, gamitin ang app secret, at ikumpara sa halagang kasunod ng s= sa halip na sa buong header.
Paano ko i-verify ang mga TikTok event na ipinasa ng easyCoexistence?
Gamit ang X-EC-Signature at ang signing secret na ipinakita noong itinakda ang destination: kalkulahin muli ang HMAC-SHA256 sa t, tuldok, at raw body, ikumpara ito sa v1, at tanggihan ang t na mahigit 5 minuto na ang edad.
Magpatuloy sa pagbabasa
I-connect ang inyong unang channel sa loob ng dalawang minuto.
Walang review ng platform na hihintayin. I-connect ang WhatsApp, Instagram, TikTok o iba pang channel, pagkatapos ay utusan ang inyong AI na mag-post, mag-reply o gumawa ng report, at panoorin itong gumana.
- 3 araw na libre
- Mag-cancel anumang oras
- Official API lang
- Minomonitor 24/7
Na-verify noong