InloggenGratis proefperiode starten
easyCoexistence Officiële API's

TikTok-webhooks verifiëren: de Tiktok-Signature-header en hoe je die controleert

TikTok's API for Business ondertekent elke webhook-levering in een Tiktok-Signature-header van de vorm t=<unix-seconden>,s=<hex>. Daarin is s een HMAC-SHA256 van de waarde van t, een punt en de body van het verzoek, gesleuteld met het geheim van de developer-app. Om een levering te verifiëren, bereken je die HMAC opnieuw over de ruwe body zoals die binnenkwam, vergelijk je die met s in constante tijd en wijs je een verouderde t af.

easyCoexistence controleert de handtekening van TikTok op elke reactiegebeurtenis die zijn app ontvangt en stuurt de reactiegebeurtenissen van het verbonden account door naar je HTTPS-endpoint, ondertekend in X-EC-Signature met een geheim voor dat account alleen.

t and s

De twee delen van Tiktok-Signature: het Unix-tijdstempel van de levering in seconden en de handtekening die TikTok ervoor genereerde.

5 seconds

De acceptableDelay in het Node-voorbeeld van TikTok, die een correct ondertekende levering weigert als die ouder is dan die waarde.

x-tt-logid

Header met de unieke ID van elke levering, die TikTok vraagt ontvangers te loggen voor probleemoplossing.

BRAND_MENTION

Gebeurtenistype voor vermeldingswebhooks, waarvan de abonnementsgids naar dezelfde verificatie van de handtekening verwijst.

v1

Het handtekeningdeel van de X-EC-Signature-header van easyCoexistence, een HMAC-SHA256 van t, een punt en de ruwe body.

Hoe ziet de Tiktok-Signature-header eruit?

Twee delen, gescheiden door een komma: t, het Unix-tijdstempel in seconden van die levering, en s, de handtekening, 64 hexadecimale tekens lang. De pagina's van TikTok schrijven de naam als TikTok-Signature, Tiktok-Signature en tiktok-signature. HTTP-headernamen zijn niet hoofdlettergevoelig, dus lees de header zonder op hoofdletters te letten, zoals de meeste frameworks al doen. De overige headers in het voorbeeld van 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

Welke bytes ondertekent TikTok?

De t-waarde als string, een punt en daarna de body. De gids van TikTok noemt dat laatste deel een als tekst geserialiseerde JSON-kopie van de body van het verzoek, en het Node-voorbeeld bouwt die kopie opnieuw op door JSON.stringify uit te voeren op een al geparst object. Dat reproduceert de bytes van TikTok alleen zolang beide serialisers het eens zijn over spaties, sleutelvolgorde en escaping. Hash daarom de body precies zoals hij binnenkwam, voordat enige JSON-middleware hem leest.

Welk geheim is de sleutel?

Het geheim van de developer-app, te vinden onder My Apps, App Detail, Basic Information in het developerportaal van TikTok. Het is de waarde die de app al meestuurt als secret naar /business/webhook/update/ en als client_secret naar de endpoints voor het token. Eén geheim ondertekent de leveringen voor elk account dat de app heeft geautoriseerd, dus een ontvanger heeft geen sleutel per account nodig, en noch het toegangstoken noch de app-ID speelt een rol.

Hoe controleer je het in Node.js?

Met node:crypto en de ruwe body. De onderstaande functie splitst de header, berekent de HMAC opnieuw over t, het punt en de bytes van de body, vergelijkt het resultaat in constante tijd en controleert daarna de leeftijd van t. Het krijgt de naam van het handtekeningdeel als argument, zodat dezelfde code ook de leveringen controleert die easyCoexistence doorstuurt, waar dat deel v1 heet en de sleutel het ondertekeningsgeheim van het account is:

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

Hoe oud mag een levering zijn voordat je haar weigert?

TikTok laat de grens aan de ontvanger over: bereken het verschil tussen je klok en t, zegt de gids, en beslis of dat acceptabel is. Het Node-voorbeeld staat 5 seconden toe, zo strak dat een serverklok die een paar seconden afwijkt echte leveringen kan weigeren. De code hierboven staat 300 toe, het venster dat easyCoexistence ontvangers vraagt te gebruiken voor de leveringen die het zelf doorstuurt. Meet vanaf t, het leveringstijdstip dat de handtekening dekt, niet vanaf create_time in de body, dat aangeeft wanneer de gebeurtenis plaatsvond. In het voorbeeld van TikTok valt t één seconde na create_time.

Wat moet het endpoint antwoorden?

Een 200 zodra de handtekening klopt, met het werk daarna, want TikTok behandelt elke andere status als mislukte levering en stuurt haar opnieuw. Bij een handtekening die niet overeenkomt, antwoordt het voorbeeld van TikTok met een 4xx-status en logt het de x-tt-logid-header, die het verzoek identificeert als je een probleem bij TikTok meldt. client_key in de body noemt de developer-app, dus vergelijken met je eigen app-ID is een goedkope tweede controle.

Hoe wordt de callback-URL geregistreerd, en wordt die geverifieerd?

Met één API-aanroep, en TikTok documenteert geen challenge-verzoek dat de URL eerst test. POST /business/webhook/update/ vraagt om de app_id, het geheim, een event_type en een HTTPS-callback_url: VIDEO voor publicatiegebeurtenissen, COMMENT voor comment.update en, bij de Mentions API, BRAND_MENTION voor brand.mention.event. Alle drie komen op dezelfde manier ondertekend aan, en GET /business/webhook/list/ toont de URL die voor een gebeurtenistype is geregistreerd. Het bewijs van herkomst is de handtekening op elke levering.

Kun je Tiktok-Signature controleren op gebeurtenissen die easyCoexistence doorstuurt?

Nee, en dat is ook niet nodig. TikTok ondertekent die leveringen met het geheim van de eigen developer-app van easyCoexistence, dat geen enkele tool of API vrijgeeft. easyCoexistence controleert die handtekening zodra de gebeurtenis binnenkomt, antwoordt met 401 op een mislukte controle, negeert een body waarvan client_key een andere app noemt, en ondertekent daarna de doorgestuurde levering naar jou in X-EC-Signature met het ondertekeningsgeheim van dat verbonden account.

Hoe ondertekent easyCoexistence wat het doorstuurt?

In de X-EC-Signature-header, t=<unix>,v1=<hex>, waarbij t het moment van doorsturen is en v1 de hex-HMAC-SHA256 van t, een punt en de body precies zoals verzonden. De sleutel is het ondertekeningsgeheim van het account, whsec_ gevolgd door 32 tekens, en wordt geheel gebruikt, inclusief het voorvoegsel. Van de eigen headers zet easyCoexistence alleen Content-Type en deze header, zonder eventheader, dus lees de naam van de gebeurtenis uit 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))

Wat gebeurt er als het ondertekeningsgeheim wordt vervangen?

Het nieuwe geheim ondertekent vanaf de volgende doorgestuurde levering. Opnieuw aanroepen van set_social_webhook_destination of PUT /channels/{id}/webhook geeft een nieuw geheim terug en trekt het oude meteen in, en elke levering wordt maar één keer verzonden, dus een gebeurtenis die je server tijdens de overgang weigert, gaat verloren. Accepteer beide geheimen een paar minuten terwijl het nieuwe wordt uitgerold. Statusgebeurtenissen over kanalen en berichten gebruiken een ander geheim, dat uit Dashboard, Profile, Developers komt, en arriveren met de headers X-EC-Event en X-EC-Delivery, met ongeveer 33 uur aan nieuwe pogingen.

Veelgemaakte fouten

  • De body verifiëren nadat het framework die al heeft geparst. JSON-middleware geeft een object door, en opnieuw serialiseren kan de bytes van TikTok veranderen; lees de ruwe body op de webhookroute.
  • Met 200 antwoorden op een levering waarvan de handtekening faalde. TikTok stopt met het versturen van een gebeurtenis zodra het een 200 ziet, dus een echte gebeurtenis die een verkeerd ingestelde controle weigert, gaat verloren; een 4xx laat TikTok tot 72 uur opnieuw proberen.
  • Handtekeningen vergelijken met ===, zoals het voorbeeld van TikTok doet. Een vergelijking in constante tijd, zoals timingSafeEqual, onthult niet hoeveel van een vervalste handtekening overeenkwam.
  • Het geheim van easyCoexistence base64-decoderen of het whsec_-voorvoegsel afknippen. De HMAC-sleutel is de volledige string, precies zoals die eenmaal is getoond.
Dit doen met EasyCoexistence

Stel het endpoint in met set_social_webhook_destination vanuit Claude of ChatGPT, of met PUT /channels/{id}/webhook. US$ 9 tot US$ 0.75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met een gratis proefperiode van 3 dagen.

Veelgestelde vragen

Wat is x-tt-logid in een TikTok-webhook?

Een header met de unieke ID van elke levering. TikTok vraagt ontvangers die te loggen, omdat die het verzoek identificeert als je een probleem bij TikTok meldt.

Stuurt TikTok een challenge om een nieuwe webhook-URL te verifiëren?

TikTok documenteert er geen voor zijn API for Business. Met de aanroep naar /business/webhook/update/ registreer je de URL, en leveringen komen daarna met Tiktok-Signature aan zodat je server die kan controleren.

Waarom komt mijn TikTok-webhookhandtekening nooit overeen?

Controleer de invoer en de sleutel: de HMAC moet t, een punt en de ruwe body zoals ontvangen omvatten, het app-geheim gebruiken, en vergeleken worden met de waarde na s= in plaats van de hele header.

Hoe verifieer je TikTok-gebeurtenissen die easyCoexistence doorstuurt?

Met X-EC-Signature en het ondertekeningsgeheim dat je ziet bij het instellen van de bestemming: bereken HMAC-SHA256 over t, een punt en de ruwe body, vergelijk die met v1, en weiger een t die ouder is dan 5 minuten.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op