Prijavite seZapočnite besplatni probni period
easyCoexistence Zvanični API-ji

Verifikacija TikTok webhook-ova: zaglavlje potpisa i kako ga proveriti

TikTok API for Business potpisuje svaku isporuku webhook-a u zaglavlju Tiktok-Signature oblika t=<unix sekunde>,s=<hex>, gde je s HMAC-SHA256 vrednosti t, tačke i tela zahteva, sa ključem tajne developer aplikacije. Da biste ga proverili, ponovo izračunajte taj HMAC nad sirovim telom kako je stiglo, uporedite ga sa s u konstantnom vremenu i odbacite zastareli t.

easyCoexistence proverava TikTok potpis na svakom događaju komentara koji njegova aplikacija primi, a zatim prosleđuje događaje komentara povezanog naloga na vaš HTTPS endpoint, potpisane u X-EC-Signature tajnom koja važi samo za taj nalog.

t and s

Dva dela zaglavlja Tiktok-Signature: Unix vremenska oznaka isporuke u sekundama i potpis koji je TikTok za nju generisao.

5 seconds

acceptableDelay u Node primeru kompanije TikTok, koji odbija ispravno potpisanu isporuku stariju od tog roka.

x-tt-logid

Zaglavlje koje nosi jedinstveni ID svake isporuke, koji TikTok traži da primaoci beleže radi rešavanja problema.

BRAND_MENTION

Tip događaja za webhook-ove pominjanja, čiji vodič za pretplatu upućuje na istu proveru potpisa.

v1

Deo potpisa u zaglavlju X-EC-Signature iz easyCoexistence, HMAC-SHA256 od t, tačke i sirovog tela.

Kako izgleda zaglavlje Tiktok-Signature?

Dva dela, odvojena zarezom: t, Unix vremenska oznaka u sekundama te isporuke, i s, potpis, dugačak 64 heksadecimalna znaka. TikTok na svojim stranicama piše naziv kao TikTok-Signature, Tiktok-Signature i tiktok-signature. HTTP nazivi zaglavlja ne razlikuju velika i mala slova, pa ga čitajte bez obzira na veličinu slova, kao što već čine većina okvira. Ostala zaglavlja na primeru isporuke kompanije 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

Koje bajtove TikTok potpisuje?

Vrednost t kao niz znakova, tačku, pa telo. TikTok u vodiču taj poslednji deo naziva stringifikovanom JSON kopijom tela zahteva, a njegov Node primer pravi kopiju tako što JSON.stringify pokrene nad već parsiranim objektom. To reprodukuje TikTokove bajtove samo dok oba serijalizatora slažu razmake, redosled ključeva i escape-ovanje, zato heširajte telo tačno kako je stiglo, pre nego što ga JSON middleware obradi.

Koja tajna je ključ?

Tajna developer aplikacije, pronađena pod My Apps, App Detail, Basic Information na TikTok developer portalu. To je vrednost koju aplikacija već šalje kao secret ka /business/webhook/update/ i kao client_secret na token endpointima. Jedna tajna potpisuje isporuke za svaki nalog koji je ovlastio aplikaciju, pa primaocu nije potreban ključ po nalogu, a ni access token ni ID aplikacije nisu deo potpisa.

Kako se proverava u Node.js?

Pomoću node:crypto i sirovog tela. Funkcija ispod deli zaglavlje, ponovo izračunava HMAC nad t, tačkom i bajtovima tela, poredi rezultat u konstantnom vremenu, pa proverava starost t. Ime dela potpisa prima kao argument, tako da isti kod proverava i prosleđivanja iz easyCoexistence, gde se taj deo zove v1, a ključ je tajni potpisni ključ naloga:

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
});

Koliko isporuka sme biti stara pre nego što je odbijete?

TikTok prepušta granicu primaocu: izračunajte razliku između svog sata i t, kaže vodič, pa odlučite je li prihvatljiva. Njegov Node primer dozvoljava 5 sekundi, što je toliko usko da server čiji je sat nekoliko sekundi pomeren može odbiti autentične isporuke. Kod iznad dozvoljava 300, prozor koji easyCoexistence traži od primalaca za sopstvena prosleđivanja. Merite od t, vremena isporuke koje potpis pokriva, a ne od create_time u telu, koji označava kada se događaj desio. U TikTok primeru t pada sekundu posle create_time.

Šta endpoint treba da odgovori?

200 čim se potpis slaže, a posao se obavlja naknadno, jer TikTok svaki drugi status tretira kao neuspelu isporuku i šalje je ponovo. Za potpis koji se ne poklapa, TikTokov primer odgovara statusom 4xx i beleži zaglavlje x-tt-logid, koje identifikuje zahtev ako prijavite problem TikToku. client_key u telu imenuje developer aplikaciju, pa je poređenje sa sopstvenim ID-jem aplikacije jeftina dodatna provera.

Kako se registruje callback URL i da li se proverava?

Jednim pozivom API-ja, a TikTok ne dokumentuje nikakav izazovni zahtev koji bi prvo testirao URL. POST /business/webhook/update/ prima app_id, secret, event_type i HTTPS callback_url: VIDEO za događaje objavljivanja, COMMENT za comment.update i, na Mentions API-ju, BRAND_MENTION za brand.mention.event. Sva tri stižu potpisana na isti način, a GET /business/webhook/list/ prikazuje URL registrovan za tip događaja. Dokaz porekla je potpis na svakoj isporuci.

Može li se Tiktok-Signature proveriti na događajima koje easyCoexistence prosleđuje?

Ne, i za to nema potrebe. TikTok potpisuje te isporuke tajnom sopstvene developer aplikacije easyCoexistence, koju nijedan alat ni API ne izdaje. easyCoexistence proverava taj potpis čim događaj stigne, odgovara 401 na neuspeli, ignoriše telo čiji client_key imenuje drugu aplikaciju, a zatim prosleđivanje vam potpisuje u X-EC-Signature tajnim potpisnim ključem tog povezanog naloga.

Kako easyCoexistence potpisuje ono što prosleđuje?

U zaglavlju X-EC-Signature, t=<unix>,v1=<hex>, gde je t vreme prosleđivanja, a v1 hex HMAC-SHA256 od t, tačke i tela tačno onako kako je poslato. Ključ je potpisni ključ naloga, whsec_ nakon kojeg sledi 32 znaka, korišćen celokupan, uključujući prefiks. Od svojih zaglavlja easyCoexistence postavlja samo Content-Type i ovo, bez zaglavlja za događaj, pa naziv događaja čitajte iz 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))

Šta se dešava kada se potpisna tajna zameni?

Nova tajna potpisuje od sledećeg prosleđivanja. Pozivanje set_social_webhook_destination ili PUT /channels/{id}/webhook ponovo vraća svežu tajnu i odmah povlači staru, a svako prosleđivanje šalje se samo jednom, pa događaj koji server odbije tokom prebacivanja biva izgubljen. Prihvatite obe tajne nekoliko minuta dok se nova postavlja. Statusni događaji o kanalima i objavama koriste drugu tajnu, onu iz Dashboard, Profile, Developers, i stižu sa zaglavljima X-EC-Event i X-EC-Delivery, uz ponovne pokušaje oko 33 sata.

Česte greške

  • Provera tela koje je okvir već obradio. JSON middleware predaje objekat, a njegovo ponovno serijalizovanje može promeniti TikTokove bajtove; čitajte sirovo telo na webhook ruti.
  • Odgovor 200 na isporuku čiji potpis nije prošao. TikTok prestaje da šalje događaj čim vidi 200, pa se autentičan događaj koji je odbijen zbog pogrešno podešene provere gubi; 4xx ostavlja TikTok da pokušava do 72 sata.
  • Poređenje potpisa sa ===, kao u TikTokovom primeru. Poređenje u konstantnom vremenu, poput timingSafeEqual, ne otkriva koliko se lažni potpis poklopio.
  • Dekodiranje tajne easyCoexistence iz Base64 ili odsecanje prefiksa whsec_. HMAC ključ je ceo niz, tačno onako kako je jednom prikazan.
Ovo radite uz EasyCoexistence

Endpoint postavite pomoću set_social_webhook_destination u Claude ili ChatGPT, ili pomoću PUT /channels/{id}/webhook. US$ 9 do US$ 0,75 po vezi mesečno, sa cenom koja pada kako dodajete veze, a prva 3 dana su besplatna.

Često postavljana pitanja

Šta je x-tt-logid u TikTok webhook-u?

Zaglavlje koje nosi jedinstveni ID svake isporuke. TikTok traži od primalaca da ga beleže, jer identifikuje zahtev kada prijavite problem TikToku.

Da li TikTok šalje izazov radi provere novog webhook URL-a?

TikTok za svoj API for Business ne dokumentuje nijedan. Poziv /business/webhook/update/ registruje URL, a isporuke potom stižu sa Tiktok-Signature koji vaš server proverava.

Zašto se potpis mog TikTok webhook-a nikada ne poklapa?

Proverite ulaz i ključ: HMAC mora da pokriva t, tačku i sirovo telo kako je stiglo, koristi tajnu aplikacije i poredi se sa vrednošću iza s= a ne sa celim zaglavljem.

Kako proveriti TikTok događaje koje prosleđuje easyCoexistence?

Pomoću X-EC-Signature i potpisne tajne prikazane kada postavite odredište: ponovo izračunajte HMAC-SHA256 nad t, tačkom i sirovim telom, uporedite ga sa v1 i odbacite t stariji od 5 minuta.

Nastavite sa čitanjem

Povežite prvi kanal za dva minuta.

Bez čekanja na odobrenja platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoj AI da objavi, odgovori ili napravi izveštaj, i gledajte kako radi.

  • 3 dana besplatno
  • Otkažite bilo kada
  • Samo zvanični API-ji
  • Nadzor 24/7

Provereno na