IngiaAnza kipindi cha majaribio bila malipo
easyCoexistence API rasmi

Kuthibitisha webhook za TikTok: header ya sahihi na jinsi ya kuikagua

TikTok's API for Business husaini kila utumaji wa webhook kwenye header ya Tiktok-Signature yenye umbo la t=<unix seconds>,s=<hex>, ambapo s ni HMAC-SHA256 ya thamani ya t, nukta, na mwili wa ombi, kwa kutumia siri ya app ya msanidi kama ufunguo. Ili kuithibitisha, hesabu tena HMAC hiyo juu ya mwili ghafi kama ulivyopokelewa, linganisha na s kwa muda usiobadilika, kisha kataa t iliyopitwa na wakati.

easyCoexistence inakagua sahihi ya TikTok kwenye kila tukio la maoni linalofika kwenye app yake, kisha inatuma matukio ya maoni ya akaunti iliyounganishwa kwenye endpoint yako ya HTTPS, ikisainiwa kwenye X-EC-Signature kwa siri ya akaunti hiyo pekee.

t and s

Sehemu mbili za Tiktok-Signature: saa ya Unix ya utumaji huo kwa sekunde, na sahihi ambayo TikTok iliizalisha kwa ajili yake.

5 seconds

acceptableDelay katika mfano wa Node.js wa TikTok, ambao unakataa utumaji uliosainiwa vizuri lakini wa zamani kuliko muda huo.

x-tt-logid

Header inayobeba kitambulisho cha kipekee cha kila utumaji, ambacho TikTok inaomba wapokeaji wakiandike kwenye kumbukumbu kwa ajili ya utatuzi.

BRAND_MENTION

Aina ya tukio kwa webhook za kutajwa, ambazo mwongozo wa usajili unaelekeza kwenye uthibitishaji huo huo wa sahihi.

v1

Sehemu ya sahihi ya header ya X-EC-Signature ya easyCoexistence: HMAC-SHA256 ya t, nukta, na mwili ghafi.

Header ya Tiktok-Signature inaonekanaje?

Ina sehemu mbili zilizotenganishwa kwa koma: t, saa ya Unix kwa sekunde ya utumaji huo, na s, sahihi yenye herufi 64 za hexadecimal. Kurasa za TikTok huandika jina kama TikTok-Signature, Tiktok-Signature na tiktok-signature. Majina ya header za HTTP hayajali herufi kubwa au ndogo, kwa hiyo yasome bila kujali kesi, kama mifumo mingi tayari inavyofanya. Header nyingine kwenye utumaji wa mfano wa TikTok:

Headers from TikTok's sample delivery
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 inasaini baiti zipi?

Thamani ya t kama mfuatano, kisha nukta, kisha mwili. Mwongozo wa TikTok unaita kipengele cha mwisho nakala ya mwili wa ombi iliyogeuzwa kuwa JSON ya mfuatano, na mfano wake wa Node.js unajenga nakala hiyo upya kwa kuendesha JSON.stringify kwenye kitu kilichokwisha kuchanganuliwa. Njia hiyo huzalisha baiti za TikTok tu wakati mifumo yote miwili ya kugeuza JSON inakubaliana kuhusu nafasi, mpangilio wa funguo na escaping. Kwa hiyo hesabu HMAC ya mwili kama ulivyofika, kabla ya middleware yoyote ya JSON kuusoma.

Siri gani ni ufunguo?

Siri ya app ya msanidi, inayopatikana chini ya My Apps, App Detail, Basic Information kwenye lango la wasanidi la TikTok. Ni thamani ambayo app tayari inatuma kama secret kwa /business/webhook/update/ na kama client_secret kwenye token endpoints. Siri moja husaini utumaji kwa kila akaunti iliyoidhinisha app, kwa hiyo mpokeaji hahitaji ufunguo kwa kila akaunti, na access token wala app ID haishiriki.

Unaikagua vipi kwenye Node.js?

Kwa node:crypto na mwili ghafi. Kazi iliyo hapa chini inagawanya header, inahesabu upya HMAC juu ya t, nukta na baiti za mwili, inalinganisha matokeo kwa muda usiobadilika, kisha inakagua umri wa t. Inapokea jina la sehemu ya sahihi kama hoja, kwa hiyo msimbo huo huo pia unakagua forwards za easyCoexistence, ambapo sehemu hiyo inaitwa v1 na ufunguo ni siri ya sahihi ya akaunti:

Node.js and Express: TikTok's deliveries and easyCoexistence's forwards
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
});

Utumaji unaweza kuwa wa zamani kiasi gani kabla ya kuukataa?

TikTok inamwachia mpokeaji kuamua mpaka: kokotoa tofauti kati ya saa yako na t, kama mwongozo wake unavyosema, kisha uamue kama inakubalika. Mfano wake wa Node.js unaruhusu sekunde 5, finyu kiasi kwamba saa ya seva iliyochelewa sekunde chache inaweza kukataa utumaji halisi. Msimbo hapo juu unaruhusu 300, dirisha ambalo easyCoexistence inawaomba wapokeaji watumie kwenye forwards zake. Pima kutoka t, muda wa utumaji ambao sahihi inaufunika, si kutoka create_time kwenye mwili, ambayo inaonyesha wakati tukio lilipotokea. Kwenye mfano wa TikTok, t iko sekunde moja baada ya create_time.

Endpoint inapaswa kujibu nini?

200 mara tu sahihi inapothibitika, huku kazi ikifanywa baadaye, kwa sababu TikTok inachukulia hali nyingine yoyote kuwa utumaji ulioshindwa na kuutuma tena. Kwa sahihi isiyolingana, mfano wa TikTok unajibu kwa hali ya 4xx na kuandika header ya x-tt-logid kwenye kumbukumbu, ambayo hutambulisha ombi ukiripoti tatizo kwa TikTok. client_key kwenye mwili inataja app ya msanidi, kwa hiyo kuilinganisha na app ID yako ni ukaguzi wa pili wa gharama nafuu.

Callback URL inasajiliwa vipi, na je, inathibitishwa?

Kwa wito mmoja wa API, na TikTok haiandiki ombi lolote la changamoto linalojaribu URL kwanza. POST /business/webhook/update/ inapokea app_id, secret, event_type na callback_url ya HTTPS: VIDEO kwa matukio ya uchapishaji, COMMENT kwa comment.update na, kwenye Mentions API, BRAND_MENTION kwa brand.mention.event. Yote matatu hufika yakisainiwa kwa njia ile ile, na GET /business/webhook/list/ inaonyesha URL iliyosajiliwa kwa kila aina ya tukio. Uthibitisho wa asili ni sahihi kwenye kila utumaji.

Je, unaweza kukagua Tiktok-Signature kwenye matukio ambayo easyCoexistence inatuma kwako?

Hapana, na hakuna sababu ya kufanya hivyo. TikTok inasaini utumaji huo kwa siri ya app ya msanidi ya easyCoexistence yenyewe, ambayo hakuna zana wala API inayoitoa. easyCoexistence inakagua sahihi hiyo tukio linapofika, inajibu 401 kwa ile inayoshindwa, inapuuza mwili ambao client_key yake inataja app nyingine, kisha inasaini forward yake kwako kwenye X-EC-Signature kwa siri ya sahihi ya akaunti hiyo iliyounganishwa.

easyCoexistence inasainije kile inachotuma?

Kwenye header ya X-EC-Signature, t=<unix>,v1=<hex>, ambapo t ni muda wa forward na v1 ni HMAC-SHA256 ya hex ya t, nukta na mwili kama ulivyotumwa. Ufunguo ni siri ya sahihi ya akaunti, yaani whsec_ ikifuatiwa na herufi 32, ikitumika yote pamoja na kiambishi. Kati ya header zake, easyCoexistence huweka Content-Type na hii tu, bila header ya tukio, kwa hiyo soma jina la tukio kutoka entry.event:

A forwarded TikTok comment event, as sent
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))

Nini kinatokea siri ya sahihi inapobadilishwa?

Siri mpya inaanza kusaini kuanzia forward inayofuata. Kuita set_social_webhook_destination au PUT /channels/{id}/webhook tena kunarudisha siri mpya na kuondoa ya zamani papo hapo. Kila forward hutumwa mara moja tu, kwa hiyo tukio ambalo seva yako inalikataa wakati wa kubadilisha linapotea. Kubali siri zote mbili kwa dakika chache wakati mpya inasambazwa. Matukio ya hali ya chaneli na machapisho hutumia siri nyingine, ile ya Dashboard, Profile, Developers, na hufika na header za X-EC-Event na X-EC-Delivery, zikijaribiwa tena kwa takriban saa 33.

Makosa ya kawaida

  • Kuthibitisha mwili ambao framework tayari imeuchanganua. Middleware ya JSON hukupa kitu, na kukiserialize upya kunaweza kubadilisha baiti za TikTok, kwa hiyo soma mwili ghafi kwenye route ya webhook.
  • Kujibu 200 kwa utumaji ambao sahihi yake ilishindwa. TikTok inaacha kutuma tukio mara inapoona 200, kwa hiyo tukio halisi lililokataliwa na ukaguzi uliopangwa vibaya linapotea. Hali ya 4xx huifanya TikTok ijaribu tena hadi saa 72.
  • Kulinganisha sahihi kwa ===, kama mfano wa TikTok unavyofanya. Ulinganishaji wa muda usiobadilika kama timingSafeEqual hauonyeshi ni kiasi gani cha sahihi ghushi kililingana.
  • Kufungua base64 siri ya easyCoexistence au kukata kiambishi chake cha whsec_. Ufunguo wa HMAC ni mfuatano mzima, kama ulivyoonyeshwa mara moja.
Kufanya hili ukitumia EasyCoexistence

Weka endpoint kwa set_social_webhook_destination kutoka Claude au ChatGPT, au kwa PUT /channels/{id}/webhook. US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, bei inashuka unapoongeza miunganisho, na siku 3 za kwanza ni bure.

Maswali yanayoulizwa mara kwa mara

x-tt-logid kwenye webhook ya TikTok ni nini?

Ni header inayobeba kitambulisho cha kipekee cha kila utumaji. TikTok inaomba wapokeaji wakiandike kwenye kumbukumbu, kwa sababu kinatambulisha ombi unaporipoti tatizo kwa TikTok.

Je, TikTok hutuma changamoto kuthibitisha URL mpya ya webhook?

TikTok haiandiki changamoto yoyote kwa API for Business yake. Wito wa /business/webhook/update/ husajili URL, kisha utumaji hufika ukiwa na Tiktok-Signature kwa seva yako kukagua.

Kwa nini sahihi ya webhook yangu ya TikTok hailingani kamwe?

Kagua ingizo na ufunguo: HMAC lazima ifunike t, nukta na mwili ghafi kama ulivyopokelewa, itumie siri ya app, na ilinganishwe na thamani iliyo baada ya s= badala ya header nzima.

Ninawezaje kuthibitisha matukio ya TikTok yaliyotumwa na easyCoexistence?

Kwa X-EC-Signature na siri ya sahihi iliyoonyeshwa ulipoweka destination: kokotoa upya HMAC-SHA256 juu ya t, nukta na mwili ghafi, linganisha na v1, kisha ukatae t ya zaidi ya dakika 5.

Endelea kusoma

Unganisha chaneli yako ya kwanza ndani ya dakika mbili.

Hakuna ukaguzi wa majukwaa wa kusubiri. Unganisha WhatsApp, Instagram, TikTok au chaneli nyingine, kisha mwombe AI wako achapishe, ajibu au atoe ripoti, na uone akifanya kazi.

  • Siku 3 bila malipo
  • Ghairi wakati wowote
  • API rasmi pekee
  • Hufuatiliwa saa 24/7

Imethibitishwa kwenye