Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Verificarea webhook-urilor TikTok: antetul de semnătură și cum îl verificați

TikTok semnează fiecare livrare webhook din API for Business într-un antet Tiktok-Signature de forma t=<secunde unix>,s=<hex>, unde s este un HMAC-SHA256 al valorii t, al unui punct și al corpului cererii, cu secretul aplicației de dezvoltator drept cheie. Pentru verificare, recalculați acest HMAC peste corpul brut, exact cum a fost primit, comparați-l cu s în timp constant și respingeți un t vechi.

easyCoexistence verifică semnătura TikTok la fiecare eveniment de comentariu pe care îl primește aplicația sa, apoi redirecționează evenimentele de comentariu ale contului conectat către endpoint-ul dumneavoastră HTTPS, semnate în X-EC-Signature cu un secret propriu acelui cont.

t and s

Cele două părți ale Tiktok-Signature: marcajul de timp Unix al livrării, în secunde, și semnătura generată de TikTok pentru ea.

5 seconds

Valoarea acceptableDelay din exemplul Node al TikTok, care respinge o livrare semnată corect, dar mai veche decât acest prag.

x-tt-logid

Antetul care poartă ID-ul unic al fiecărei livrări, pe care TikTok cere destinatarilor să-l înregistreze pentru depanare.

BRAND_MENTION

Tipul de eveniment pentru webhook-urile de mențiuni, al căror ghid de abonare trimite la aceeași verificare a semnăturii.

v1

Partea de semnătură din antetul X-EC-Signature al easyCoexistence, un HMAC-SHA256 al lui t, al unui punct și al corpului brut.

Cum arată antetul Tiktok-Signature?

Două părți, separate printr-o virgulă: t, marcajul de timp Unix al livrării respective, în secunde, și s, semnătura, lungă de 64 de caractere hexazecimale. Paginile TikTok scriu numele ca TikTok-Signature, Tiktok-Signature și tiktok-signature; numele antetelor HTTP nu fac distincție între majuscule și minuscule, deci citiți-l fără a ține cont de literă, cum fac deja majoritatea framework-urilor. Celelalte antete din exemplul de livrare al 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

Ce octeți semnează TikTok?

Valoarea t ca șir de caractere, un punct, apoi corpul. Ghidul TikTok numește această ultimă parte o copie JSON serializată a corpului cererii, iar exemplul său Node reface copia rulând JSON.stringify pe un obiect deja parsat. Așa se reproduc octeții TikTok doar dacă ambele serializatoare coincid în privința spațierii, a ordinii cheilor și a escaping-ului. Calculați deci HMAC-ul peste corpul exact cum a sosit, înainte ca vreun middleware JSON să-l citească.

Ce secret este cheia?

Secretul aplicației de dezvoltator, găsit în My Apps, App Detail, Basic Information din portalul pentru dezvoltatori TikTok. Este valoarea pe care aplicația o trimite deja ca secret către /business/webhook/update/ și ca client_secret către endpoint-urile pentru token. Un singur secret semnează livrările pentru fiecare cont care a autorizat aplicația, deci un receptor nu are nevoie de o cheie per cont, iar nici token-ul de acces, nici ID-ul aplicației nu intră în calcul.

Cum verificați în Node.js?

Cu node:crypto și corpul brut. Funcția de mai jos desparte antetul, recalculează HMAC-ul peste t, punct și octeții corpului, compară rezultatul în timp constant și apoi verifică vârsta lui t. Primește numele părții de semnătură ca argument, astfel că același cod verifică și redirecționările easyCoexistence, unde partea se numește v1 și cheia este secretul de semnare al contului:

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

Cât de veche poate fi o livrare înainte să o refuzați?

TikTok lasă limita în seama receptorului: calculați diferența dintre ceasul dumneavoastră și t, spune ghidul, și decideți dacă este tolerabilă. Exemplul său Node acceptă 5 secunde, atât de strâns încât un server al cărui ceas diferă cu câteva secunde ar putea refuza livrări autentice; codul de mai sus acceptă 300, fereastra pe care easyCoexistence o cere receptorilor pentru propriile redirecționări. Măsurați din t, momentul livrării acoperit de semnătură, nu din create_time din corp, care marchează momentul producerii evenimentului. În exemplul TikTok, t cade cu o secundă după create_time.

Ce ar trebui să răspundă endpoint-ul?

Un 200 imediat ce semnătura este validă, iar lucrul efectiv se face după aceea, deoarece TikTok tratează orice alt status ca livrare eșuată și o trimite din nou. Pentru o semnătură care nu se potrivește, exemplul TikTok răspunde cu un status 4xx și înregistrează antetul x-tt-logid, care identifică cererea dacă raportați o problemă către TikTok. client_key din corp indică aplicația de dezvoltator, deci compararea lui cu ID-ul propriu al aplicației este o a doua verificare ieftină.

Cum se înregistrează URL-ul de callback și este el verificat?

Printr-un singur apel API, iar TikTok nu documentează nicio cerere de provocare care să testeze mai întâi URL-ul. POST /business/webhook/update/ primește app_id, secretul, un event_type și un callback_url HTTPS: VIDEO pentru evenimentele de publicare, COMMENT pentru comment.update și, în API-ul Mentions, BRAND_MENTION pentru brand.mention.event. Toate trei sosesc semnate în același mod, iar GET /business/webhook/list/ arată URL-ul înregistrat pentru fiecare tip de eveniment. Dovada originii este semnătura de pe fiecare livrare.

Puteți verifica Tiktok-Signature pe evenimentele pe care le redirecționează easyCoexistence?

Nu, și nimic nu o cere. TikTok semnează acele livrări cu secretul aplicației de dezvoltator a easyCoexistence, pe care nu-l oferă niciun instrument și niciun API. easyCoexistence verifică semnătura respectivă pe măsură ce sosește fiecare eveniment, răspunde 401 celui care eșuează, ignoră un corp al cărui client_key indică o altă aplicație, apoi semnează redirecționarea către dumneavoastră în X-EC-Signature, cu secretul de semnare al acelui cont conectat.

Cum semnează easyCoexistence ceea ce redirecționează?

În antetul X-EC-Signature, t=<unix>,v1=<hex>, unde t este momentul redirecționării, iar v1 este HMAC-SHA256, în hexadecimal, al lui t, al unui punct și al corpului exact cum a fost trimis. Cheia este secretul de semnare al contului, whsec_ urmat de 32 de caractere, folosit integral, cu prefixul cu tot. Dintre antetele proprii, easyCoexistence setează doar Content-Type și acesta, fără un antet de eveniment, așa că citiți numele evenimentului din 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))

Ce se întâmplă când secretul de semnare este înlocuit?

Noul secret semnează de la următoarea redirecționare. Reapelarea set_social_webhook_destination sau PUT /channels/{id}/webhook returnează un secret nou și retrage imediat pe cel vechi, iar fiecare redirecționare se trimite o singură dată, deci un eveniment pe care serverul dumneavoastră îl refuză în timpul schimbării se pierde. Acceptați ambele secrete câteva minute, cât timp se implementează cel nou. Evenimentele de stare despre canale și postări folosesc alt secret, cel din Dashboard, Profile, Developers, și sosesc cu antetele X-EC-Event și X-EC-Delivery, reîncercate timp de aproximativ 33 de ore.

Greșeli frecvente

  • Verificarea unui corp pe care framework-ul l-a parsat deja. Middleware-ul JSON predă un obiect, iar serializarea lui din nou poate schimba octeții TikTok; citiți corpul brut pe ruta webhook-ului.
  • Răspunsul 200 la o livrare a cărei semnătură a eșuat. TikTok încetează să trimită un eveniment după ce vede un 200, deci unul autentic refuzat de o verificare configurată greșit se pierde; un 4xx îl lasă pe TikTok să reîncerce timp de până la 72 de ore.
  • Compararea semnăturilor cu ===, cum face exemplul TikTok. O comparație în timp constant, precum timingSafeEqual, nu dezvăluie câtă parte dintr-o semnătură falsificată s-a potrivit.
  • Decodarea în base64 a secretului easyCoexistence sau tăierea prefixului său whsec_. Cheia HMAC este șirul întreg, exact așa cum a fost afișat o singură dată.
Faceți acest lucru cu EasyCoexistence

Setați endpoint-ul cu set_social_webhook_destination din Claude sau ChatGPT, sau cu PUT /channels/{id}/webhook. US$ 9 până la US$ 0,75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, iar primele 3 zile sunt perioadă de probă gratuită.

Întrebări frecvente

Ce este x-tt-logid într-un webhook TikTok?

Un antet care poartă ID-ul unic al fiecărei livrări. TikTok cere destinatarilor să-l înregistreze, pentru că identifică cererea atunci când raportați o problemă către TikTok.

Trimite TikTok o cerere de verificare pentru un URL nou de webhook?

TikTok nu documentează niciuna pentru API for Business. Apelul /business/webhook/update/ înregistrează URL-ul, iar livrările sosesc apoi cu Tiktok-Signature pe care serverul dumneavoastră o verifică.

De ce semnătura webhook TikTok nu se potrivește niciodată?

Verificați intrarea și cheia: HMAC-ul trebuie să acopere t, un punct și corpul brut exact cum a sosit, să folosească secretul aplicației și să fie comparat cu valoarea de după s=, nu cu antetul întreg.

Cum verific evenimentele TikTok redirecționate de easyCoexistence?

Cu X-EC-Signature și secretul de semnare afișat la setarea destinației: recalculați HMAC-SHA256 peste t, un punct și corpul brut, comparați-l cu v1 și refuzați un t mai vechi de 5 minute.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la