AnmeldenKostenlose Testphase starten
easyCoexistence Offizielle APIs

TikTok-Webhooks verifizieren: der Signatur-Header und seine Prüfung

Die TikTok API for Business signiert jede Webhook-Zustellung in einem Header Tiktok-Signature der Form t=<unix seconds>,s=<hex>. Dabei ist s ein HMAC-SHA256 über den Wert von t, einen Punkt und den Anfragetext, geschlüsselt mit dem Secret der Entwickler-App. Zur Prüfung berechnen Sie diesen HMAC über den Rohtext, wie er empfangen wurde, vergleichen ihn mit s in konstanter Zeit und lehnen ein veraltetes t ab.

easyCoexistence prüft die Signatur von TikTok bei jedem Kommentarereignis, das seine App empfängt, und leitet die Kommentarereignisse des verbundenen Kontos an Ihren HTTPS-Endpoint weiter.

t and s

Die beiden Teile von Tiktok-Signature: der Unix-Zeitstempel der Zustellung in Sekunden und die Signatur, die TikTok dafür erzeugt hat.

5 seconds

Der acceptableDelay im Node-Beispiel von TikTok, das eine korrekt signierte Zustellung ablehnt, wenn sie älter als dieser Wert ist.

x-tt-logid

Header mit der eindeutigen ID jeder Zustellung, die TikTok Empfängern zur Fehlersuche zu protokollieren empfiehlt.

BRAND_MENTION

Ereignistyp für Erwähnungs-Webhooks, deren Abonnementanleitung auf dieselbe Signaturprüfung verweist.

v1

Der Signaturteil des Headers X-EC-Signature von easyCoexistence, ein HMAC-SHA256 über t, einen Punkt und den Rohtext.

Wie sieht der Header Tiktok-Signature aus?

Er besteht aus zwei Teilen, durch ein Komma getrennt: t, der Unix-Zeitstempel dieser Zustellung in Sekunden, und s, die Signatur mit 64 hexadezimalen Zeichen. Die Seiten von TikTok schreiben den Namen als TikTok-Signature, Tiktok-Signature und tiktok-signature. HTTP-Headernamen unterscheiden keine Groß- und Kleinschreibung, daher sollten Sie ihn so lesen, wie es die meisten Frameworks ohnehin tun. Die übrigen Header der Beispielzustellung von 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

Welche Bytes signiert TikTok?

Den Wert von t als Zeichenkette, einen Punkt und dann den Body. TikTok bezeichnet diesen letzten Teil in seiner Anleitung als stringifizierte JSON-Kopie des Request-Bodys, und sein Node-Beispiel baut die Kopie neu, indem es JSON.stringify auf ein bereits geparstes Objekt anwendet. Das reproduziert die Bytes von TikTok nur, solange beide Serialisierer bei Leerzeichen, Schlüsselreihenfolge und Escaping übereinstimmen. Hashen Sie den Body daher exakt so, wie er eingegangen ist, bevor eine JSON-Middleware ihn liest.

Welches Secret ist der Schlüssel?

Das Secret der Entwickler-App, zu finden unter My Apps, App Detail, Basic Information im Entwicklerportal von TikTok. Es ist derselbe Wert, den die App als secret an /business/webhook/update/ und als client_secret an die Token-Endpoints sendet. Ein Secret signiert die Zustellungen für jedes Konto, das die App autorisiert hat. Der Empfänger braucht also keinen Schlüssel pro Konto, und weder das Access-Token noch die App-ID fließen ein.

Wie prüfen Sie es in Node.js?

Mit node:crypto und dem Rohtext. Die folgende Funktion zerlegt den Header, berechnet den HMAC über t, den Punkt und die Bytes des Bodys neu, vergleicht das Ergebnis in konstanter Zeit und prüft danach das Alter von t. Sie erhält den Namen des Signaturteils als Argument, sodass derselbe Code auch die Weiterleitungen von easyCoexistence prüft, wo dieser Teil v1 heißt und der Schlüssel das Signing-Secret des Kontos ist:

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

Wie alt darf eine Zustellung sein, bevor Sie sie ablehnen?

TikTok überlässt die Grenze dem Empfänger: Berechnen Sie den Abstand zwischen Ihrer Uhr und t, heißt es in der Anleitung, und entscheiden Sie, ob er vertretbar ist. Das Node-Beispiel erlaubt 5 Sekunden, so eng, dass eine Serveruhr, die um wenige Sekunden abweicht, echte Zustellungen ablehnen könnte. Der Code oben erlaubt 300 Sekunden, das Fenster, das easyCoexistence Empfängern für die eigenen Weiterleitungen empfiehlt. Messen Sie ab t, dem Zeitpunkt der Zustellung, den die Signatur abdeckt, nicht ab create_time im Body, der angibt, wann das Ereignis eintrat. Im Beispiel von TikTok liegt t eine Sekunde nach create_time.

Was soll der Endpoint antworten?

Ein 200, sobald die Signatur stimmt, und die Arbeit erfolgt danach, denn TikTok wertet jeden anderen Status als fehlgeschlagene Zustellung und sendet sie erneut. Bei einer nicht passenden Signatur antwortet das Beispiel von TikTok mit einem 4xx-Status und protokolliert den Header x-tt-logid, der die Anfrage identifiziert, falls Sie ein Problem an TikTok melden. client_key im Body nennt die Entwickler-App, daher ist der Abgleich mit Ihrer eigenen App-ID eine einfache zweite Prüfung.

Wie wird die Callback-URL registriert, und wird sie geprüft?

Mit einem einzigen API-Aufruf, und TikTok dokumentiert keine Challenge-Anfrage, die die URL vorab testet. POST /business/webhook/update/ erwartet die app_id, das Secret, einen event_type und eine callback_url mit HTTPS: VIDEO für Veröffentlichungsereignisse, COMMENT für comment.update und, in der Mentions API, BRAND_MENTION für brand.mention.event. Alle drei kommen gleich signiert an, und GET /business/webhook/list/ zeigt die URL, die für einen Ereignistyp registriert ist. Den Herkunftsnachweis liefert die Signatur jeder Zustellung.

Können Sie Tiktok-Signature bei Ereignissen prüfen, die easyCoexistence weiterleitet?

Nein, und es ist auch nicht nötig. TikTok signiert diese Zustellungen mit dem Secret der eigenen Entwickler-App von easyCoexistence, das kein Tool und keine API herausgibt. easyCoexistence prüft diese Signatur bei jedem eintreffenden Ereignis, antwortet mit 401 auf eine fehlgeschlagene, ignoriert einen Body, dessen client_key eine andere App nennt, und signiert seine Weiterleitung an Sie anschließend in X-EC-Signature mit dem Signing-Secret des verbundenen Kontos.

Wie signiert easyCoexistence, was es weiterleitet?

Im Header X-EC-Signature, t=<unix>,v1=<hex>, wobei t der Zeitpunkt der Weiterleitung ist und v1 der hexadezimale HMAC-SHA256 über t, einen Punkt und den Body genau so, wie er gesendet wurde. Der Schlüssel ist das Signing-Secret des Kontos, whsec_ gefolgt von 32 Zeichen, vollständig verwendet, einschließlich Präfix. Von seinen eigenen Headern setzt easyCoexistence nur Content-Type und diesen, ohne Ereignis-Header. Den Namen des Ereignisses lesen Sie daher aus 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))

Was passiert, wenn das Signing-Secret ersetzt wird?

Das neue Secret signiert ab der nächsten Weiterleitung. Ein Aufruf von set_social_webhook_destination oder PUT /channels/{id}/webhook erzeugt ein frisches Secret und löst das alte sofort ab. Jede Weiterleitung wird genau einmal gesendet, daher geht ein Ereignis verloren, das Ihr Server während der Umstellung ablehnt. Akzeptieren Sie beide Secrets einige Minuten lang, während das neue ausgerollt wird. Statusereignisse zu Kanälen und Beiträgen verwenden ein anderes Secret, das unter Dashboard, Profile, Developers zu finden ist, und kommen mit den Headern X-EC-Event und X-EC-Delivery an, mit Wiederholungen über etwa 33 Stunden.

Häufige Fehler

  • Einen Body verifizieren, den das Framework bereits geparst hat. JSON-Middleware übergibt ein Objekt, und erneutes Serialisieren kann die Bytes von TikTok verändern. Lesen Sie den Rohtext auf der Webhook-Route.
  • Mit 200 auf eine Zustellung antworten, deren Signatur fehlgeschlagen ist. TikTok stellt ein Ereignis ein, sobald es ein 200 sieht, also geht ein echtes, das eine fehlerhaft konfigurierte Prüfung abgelehnt hat, verloren. Ein 4xx lässt TikTok bis zu 72 Stunden lang wiederholen.
  • Signaturen mit === vergleichen, wie es das Beispiel von TikTok tut. Ein Vergleich in konstanter Zeit wie timingSafeEqual verrät nicht, wie viel einer gefälschten Signatur übereinstimmte.
  • Das Secret von easyCoexistence base64-dekodieren oder das Präfix whsec_ abschneiden. Der HMAC-Schlüssel ist die ganze Zeichenkette, genau so, wie sie einmal angezeigt wurde.
Mit EasyCoexistence

Die Weiterleitung ist in X-EC-Signature mit einem Secret nur für dieses Konto signiert. Den Endpoint setzen Sie mit set_social_webhook_destination aus Claude oder ChatGPT oder mit PUT /channels/{id}/webhook. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit weiteren Verbindungen, die ersten 3 Tage kostenlos.

Häufig gestellte Fragen

Was ist x-tt-logid in einem TikTok-Webhook?

Ein Header mit der eindeutigen ID jeder Zustellung. TikTok bittet Empfänger, sie zu protokollieren, da sie die Anfrage identifiziert, wenn Sie ein Problem an TikTok melden.

Sendet TikTok eine Challenge zur Prüfung einer neuen Webhook-URL?

TikTok dokumentiert dafür in seiner API for Business keine. Der Aufruf /business/webhook/update/ registriert die URL, und die Zustellungen kommen dann mit Tiktok-Signature an, die Ihr Server prüfen kann.

Warum passt meine TikTok-Webhook-Signatur nie?

Prüfen Sie die Eingabe und den Schlüssel: Der HMAC muss t, den Punkt und den Rohtext genau so abdecken, wie er eingegangen ist, mit dem App-Secret gebildet und mit dem Wert hinter s= verglichen werden, nicht mit dem ganzen Header.

Wie prüfe ich TikTok-Ereignisse, die easyCoexistence weiterleitet?

Mit X-EC-Signature und dem Signing-Secret, das beim Festlegen des Ziels angezeigt wurde: Berechnen Sie HMAC-SHA256 über t, den Punkt und den Rohtext neu, vergleichen Sie ihn mit v1 und lehnen Sie ein t ab, das älter als 5 Minuten ist.

Weiterlesen

Verbinden Sie Ihren ersten Kanal in zwei Minuten.

Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.

  • 3 Tage kostenlos
  • Jederzeit kündbar
  • Nur offizielle APIs
  • Überwacht rund um die Uhr (24/7)

Verifiziert am