Prijavite seZapočnite besplatno probno razdoblje
easyCoexistence Službeni API-ji

Provjera webhookova TikToka: zaglavlje potpisa i kako ga provjeriti

Potpis svake isporuke webhooka TikTok API-ja for Business nalazi se u zaglavlju Tiktok-Signature oblika t=<unix sekunde>,s=<hex>, gdje je s HMAC-SHA256 od vrijednosti t, točke i tijela zahtjeva, potpisan tajnom razvojne aplikacije. Za provjeru ponovno izračunajte taj HMAC nad sirovim tijelom kako je primljeno, usporedite ga s s u konstantnom vremenu i odbacite zastarjeli t.

easyCoexistence provjerava TikTokov potpis na svakom događaju komentara koji primi njegova aplikacija, zatim prosljeđuje događaje komentara povezanog računa na vaš HTTPS endpoint, potpisane u X-EC-Signature tajnom samo za taj račun.

t and s

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

5 seconds

acceptableDelay u TikTokovom Node primjeru, koji odbija ispravno potpisanu isporuku stariju od tog roka.

x-tt-logid

Zaglavlje koje nosi jedinstveni ID svake isporuke, koji TikTok traži da primatelji bilježe radi rješavanja problema.

BRAND_MENTION

Vrsta događaja za webhookove spominjanja, čiji vodič o pretplati upućuje na istu provjeru potpisa.

v1

Dio potpisa u zaglavlju X-EC-Signature, koje šalje easyCoexistence: HMAC-SHA256 od t, točke i sirovog tijela.

Kako izgleda zaglavlje Tiktok-Signature?

Dva dijela odvojena zarezom: t, Unix vremenska oznaka te isporuke u sekundama, i s, potpis, dug 64 heksadecimalna znaka. TikTokove stranice pišu naziv kao TikTok-Signature, Tiktok-Signature i tiktok-signature; nazivi HTTP zaglavlja ne razlikuju velika i mala slova, pa ga čitajte neosjetljivo na velika slova, kao što to većina okvira već radi. Ostala zaglavlja u TikTokovom primjeru isporuke:

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?

Vrijednost t kao niz znakova, točku, zatim tijelo. TikTokov vodič taj posljednji dio naziva serijaliziranom JSON kopijom tijela zahtjeva, a njegov Node primjer rekonstruira kopiju pozivom JSON.stringify nad već raščlanjenim objektom. To reproducira TikTokove bajtove samo dok se oba serijalizatora slažu u razmacima, redoslijedu ključeva i escapiranju, pa HMAC izračunajte nad tijelom točno onako kako je stiglo, prije nego ga bilo koji JSON međusloj pročita.

Koja tajna služi kao ključ?

Tajna razvojne aplikacije, pronađena pod Moje aplikacije, Detalji aplikacije, Osnovni podaci na TikTokovu razvojnom portalu. To je vrijednost koju aplikacija već šalje kao secret u /business/webhook/update/ i kao client_secret na endpointima za tokene. Jedna tajna potpisuje isporuke za svaki račun koji je odobrio aplikaciju, pa primatelju ne treba ključ po računu, a u tome ne sudjeluju ni pristupni token ni ID aplikacije.

Kako to provjeriti u Node.js?

Pomoću node:crypto i sirovog tijela. Funkcija ispod raščlanjuje zaglavlje, ponovno izračunava HMAC nad t, točkom i bajtovima tijela, uspoređuje rezultat u konstantnom vremenu i zatim provjerava starost t. Prima naziv dijela potpisa kao argument, pa isti kod provjerava i easyCoexistenceove prosljeđene isporuke, gdje se taj dio zove v1, a ključ je tajna potpisivanja računa:

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 stara isporuka smije biti prije nego je odbijete?

TikTok prepušta granicu primatelju: izračunajte razliku između svog sata i t, kaže njegov vodič, pa odlučite je li prihvatljiva. Njegov Node primjer dopušta 5 sekundi, što je tijesno, pa sat poslužitelja koji zaostaje nekoliko sekundi može odbiti ispravne isporuke; kod iznad dopušta 300, prozor koji easyCoexistence traži od primatelja za vlastita prosljeđivanja. Mjerite od t, vremena isporuke koje potpis pokriva, a ne od create_time u tijelu, koji označava kada se događaj dogodio. U TikTokovu primjeru t pada jednu sekundu nakon create_time.

Što bi endpoint trebao odgovoriti?

200 čim se potpis potvrdi, a rad obavite poslije, jer TikTok svaki drugi status tretira kao neuspjelu isporuku i šalje je ponovno. Za potpis koji se ne podudara TikTokov primjer odgovara statusom 4xx i bilježi zaglavlje x-tt-logid, koje identificira zahtjev ako prijavite problem TikToku. client_key u tijelu imenuje razvojnu aplikaciju, pa je usporedba s vlastitim ID-om aplikacije jeftina druga provjera.

Kako se registrira URL za povratni poziv i provjerava li se?

Jednim pozivom API-ja, a TikTok ne dokumentira nikakav izazovni zahtjev koji bi prethodno testirao URL. POST /business/webhook/update/ prima app_id, tajnu, event_type i HTTPS callback_url: VIDEO za događaje objava, COMMENT za comment.update i, u 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 registriran za vrstu događaja. Dokaz podrijetla jest potpis na svakoj isporuci.

Mogu li provjeriti Tiktok-Signature na događajima koje easyCoexistence prosljeđuje?

Ne, i za to nema potrebe. TikTok potpisuje te isporuke tajnom vlastite razvojne aplikacije easyCoexistence, koju ne izdaje nijedan alat ni API. easyCoexistence provjerava taj potpis čim događaj stigne, onome koji ne prođe provjeru odgovara statusom 401, zanemaruje tijelo čiji client_key imenuje drugu aplikaciju, a zatim svoje prosljeđivanje potpisuje u X-EC-Signature tajnom potpisivanja tog povezanog računa.

Kako easyCoexistence potpisuje ono što prosljeđuje?

U zaglavlju X-EC-Signature, t=<unix>,v1=<hex>, gdje je t vrijeme prosljeđivanja, a v1 heksadecimalni HMAC-SHA256 od t, točke i tijela upravo onako kako je poslano. Ključ je tajna potpisivanja računa, whsec_ i 32 znaka, koristi se u cijelosti, zajedno s prefiksom. Od vlastitih zaglavlja easyCoexistence postavlja samo Content-Type i ovo, bez zaglavlja za vrstu događaja, 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))

Što se događa kada se tajna potpisivanja zamijeni?

Nova tajna potpisuje od sljedećeg prosljeđivanja. Ponovni poziv set_social_webhook_destination ili PUT /channels/{id}/webhook vraća novu tajnu i odmah poništava staru, a svako se prosljeđivanje šalje samo jednom, pa događaj koji poslužitelj odbije tijekom prijelaza biva izgubljen. Dok se nova tajna uvodi, prihvaćajte obje nekoliko minuta. Događaji o statusu za kanale i objave koriste drugu tajnu, onu iz Dashboard, Profile, Developers, i stižu sa zaglavljima X-EC-Event i X-EC-Delivery, ponovno se šalju oko 33 sata.

Uobičajene pogreške

  • Provjera tijela koje je okvir već raščlanio. JSON međusloj predaje objekt, a ponovno serijaliziranje može promijeniti TikTokove bajtove; čitajte sirovo tijelo na webhook ruti.
  • Odgovor 200 na isporuku čiji potpis nije prošao. TikTok prestaje slati događaj čim vidi 200, pa se pravi događaj koji pogrešno konfigurirana provjera odbije gubi; 4xx ostavlja TikTok da ponavlja do 72 sata.
  • Usporedba potpisa s ===, kao u TikTokovu primjeru. Usporedba u konstantnom vremenu, npr. timingSafeEqual, ne otkriva koliko se krivotvoreni potpis podudarao.
  • Dekodiranje tajne easyCoexistence iz base64 ili odrezivanje njezina prefiksa whsec_. Ključ za HMAC je cijeli niz, točno onakav kakav je jednom prikazan.
Radite ovo uz EasyCoexistence

Endpoint postavite pomoću set_social_webhook_destination iz alata Claude ili ChatGPT, ili putem PUT /channels/{id}/webhook. Od US$ 9 do US$ 0,75 po vezi mjesečno, uz pad cijene kako dodajete veze, s prvih 3 dana besplatno.

Često postavljana pitanja

Što je x-tt-logid u TikTok webhooku?

Zaglavlje koje nosi jedinstveni ID svake isporuke. TikTok traži da ga primatelji bilježe, jer identificira zahtjev kada prijavite problem TikToku.

Šalje li TikTok izazovni zahtjev radi provjere novog webhook URL-a?

Za svoj API for Business ne dokumentira nijedan. Poziv /business/webhook/update/ registrira URL, a isporuke zatim stižu s Tiktok-Signature koji vaš poslužitelj provjerava.

Zašto se moj TikTok webhook potpis nikada ne podudara?

Provjerite ulaz i ključ: HMAC mora pokrivati t, točku i sirovo tijelo kako je stiglo, koristiti tajnu aplikacije i uspoređivati se s vrijednošću nakon s=, a ne s cijelim zaglavljem.

Kako provjeriti TikTok događaje koje prosljeđuje easyCoexistence?

Pomoću X-EC-Signature i tajne potpisivanja prikazane kada postavite odredište: izračunajte HMAC-SHA256 nad t, točkom i sirovim tijelom, usporedite ga s v1 i odbacite t stariji od 5 minuta.

Nastavite čitati

Povežite svoj prvi kanal u dvije minute.

Bez čekanja na provjere platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoju umjetnu inteligenciju da objavi, odgovori ili izradi izvješće i gledajte kako radi.

  • 3 dana besplatno
  • Otkažite bilo kada
  • Samo službeni API-ji
  • Nadzor 24/7

Provjereno na