AccediInizia la prova gratuita
easyCoexistence API ufficiali

Verifica dei webhook TikTok: l'header della firma e come controllarlo

L'API for Business di TikTok firma ogni consegna di webhook in un header Tiktok-Signature nella forma t=<unix seconds>,s=<hex>, dove s è un HMAC-SHA256 del valore di t, di un punto e del corpo della richiesta, con il segreto dell'app sviluppatore come chiave. Per verificarlo, ricalcola quell'HMAC sul corpo grezzo così come è arrivato, confrontalo con s a tempo costante e rifiuta un t scaduto.

easyCoexistence verifica la firma di TikTok su ogni evento di commento che riceve la sua app, poi inoltra gli eventi di commento dell'account connesso al tuo endpoint HTTPS, firmati in X-EC-Signature con un segreto dedicato a quell'account.

t and s

Le due parti di Tiktok-Signature: il timestamp Unix della consegna in secondi e la firma generata da TikTok per essa.

5 seconds

L'acceptableDelay nell'esempio Node di TikTok, che rifiuta una consegna firmata correttamente ma più vecchia di quel valore.

x-tt-logid

L'header che riporta l'ID univoco di ogni consegna, che TikTok chiede ai ricevitori di registrare per la risoluzione dei problemi.

BRAND_MENTION

Tipo di evento per i webhook delle menzioni, la cui guida alla sottoscrizione rimanda alla stessa verifica della firma.

v1

La parte della firma dell'header X-EC-Signature di easyCoexistence, un HMAC-SHA256 di t, un punto e il corpo grezzo.

Com'è fatto l'header Tiktok-Signature?

Due parti, separate da una virgola: t, il timestamp Unix in secondi di quella consegna, e s, la firma, lunga 64 caratteri esadecimali. Le pagine di TikTok scrivono il nome come TikTok-Signature, Tiktok-Signature e tiktok-signature; i nomi degli header HTTP non distinguono maiuscole e minuscole, quindi leggilo senza fare distinzione, come già fa la maggior parte dei framework. Gli altri header dell'esempio di consegna di 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

Quali byte firma TikTok?

Il valore di t come stringa, un punto, poi il corpo. La guida di TikTok chiama quest'ultima parte una copia JSON serializzata del corpo della richiesta, e il suo esempio Node ricostruisce la copia eseguendo JSON.stringify su un oggetto già analizzato. Questo riproduce i byte di TikTok solo finché i due serializzatori concordano su spaziatura, ordine delle chiavi ed escape, quindi calcola l'hash del corpo esattamente come è arrivato, prima che qualsiasi middleware JSON lo legga.

Quale segreto è la chiave?

Il segreto dell'app sviluppatore, da trovare in My Apps, App Detail, Basic Information sul portale sviluppatori di TikTok. È il valore che l'app già invia come secret a /business/webhook/update/ e come client_secret agli endpoint dei token. Un solo segreto firma le consegne per ogni account che ha autorizzato l'app, quindi il ricevitore non ha bisogno di una chiave per account, e né il token di accesso né l'ID dell'app partecipano.

Come si verifica in Node.js?

Con node:crypto e il corpo grezzo. La funzione qui sotto divide l'header, ricalcola l'HMAC su t, sul punto e sui byte del corpo, confronta il risultato a tempo costante e poi controlla l'età di t. Riceve il nome della parte della firma come argomento, così lo stesso codice verifica anche gli inoltri di easyCoexistence, dove quella parte si chiama v1 e la chiave è il segreto di firma dell'account:

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

Quanto può essere vecchia una consegna prima di rifiutarla?

TikTok lascia la soglia al ricevitore: calcola la differenza tra il tuo orologio e t, dice la sua guida, e decidi se è tollerabile. Il suo esempio Node ammette 5 secondi, così stretto che un orologio del server sfasato di pochi secondi potrebbe rifiutare consegne genuine; il codice sopra ammette 300 secondi, la finestra che easyCoexistence chiede ai ricevitori di usare sui propri inoltri. Misura a partire da t, l'istante di consegna che la firma copre, non da create_time nel corpo, che indica quando l'evento si è verificato. Nell'esempio di TikTok, t cade un secondo dopo create_time.

Cosa deve restituire l'endpoint?

Un 200 appena la firma risulta valida, con il lavoro svolto dopo, perché TikTok considera qualsiasi altro stato una consegna fallita e la rinvia. Per una firma che non corrisponde, l'esempio di TikTok risponde con uno stato 4xx e registra l'header x-tt-logid, che identifica la richiesta se segnali un problema a TikTok. client_key nel corpo indica l'app sviluppatore, quindi confrontarlo con il tuo ID dell'app è un secondo controllo economico.

Come si registra l'URL di callback, e viene verificato?

Con una sola chiamata API, e TikTok non documenta alcuna richiesta di verifica che testi prima l'URL. POST /business/webhook/update/ richiede app_id, il secret, un event_type e un callback_url HTTPS: VIDEO per gli eventi di pubblicazione, COMMENT per comment.update e, sulla Mentions API, BRAND_MENTION per brand.mention.event. Tutti e tre arrivano firmati allo stesso modo, e GET /business/webhook/list/ mostra l'URL registrato per ogni tipo di evento. La prova dell'origine è la firma su ogni consegna.

Puoi controllare Tiktok-Signature sugli eventi che inoltra easyCoexistence?

No, e non serve. TikTok firma quelle consegne con il segreto dell'app sviluppatore di easyCoexistence, che nessuno strumento o API rende disponibile. easyCoexistence verifica quella firma all'arrivo di ogni evento, risponde 401 a una firma errata, ignora un corpo il cui client_key indica un'altra app, e poi firma il suo inoltro verso di te in X-EC-Signature con il segreto di firma di quell'account connesso.

Come firma easyCoexistence ciò che inoltra?

Nell'header X-EC-Signature, t=<unix>,v1=<hex>, dove t è l'ora dell'inoltro e v1 l'HMAC-SHA256 esadecimale di t, di un punto e del corpo esattamente come inviato. La chiave è il segreto di firma dell'account, whsec_ seguito da 32 caratteri, usato per intero, prefisso incluso. Tra i propri header, easyCoexistence imposta solo Content-Type e questo, senza un header dell'evento, quindi leggi il nome dell'evento da 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))

Cosa succede quando il segreto di firma viene sostituito?

Il nuovo segreto firma dal prossimo inoltro in poi. Richiamare set_social_webhook_destination o PUT /channels/{id}/webhook di nuovo restituisce un segreto nuovo e ritira subito il vecchio, e ogni inoltro viene inviato una sola volta, quindi un evento che il tuo server rifiuta durante il passaggio va perso. Accetta entrambi i segreti per qualche minuto, mentre il nuovo viene distribuito. Gli eventi di stato su canali e post usano un altro segreto, quello indicato in Dashboard, Profile, Developers, e arrivano con gli header X-EC-Event e X-EC-Delivery, ritentati per circa 33 ore.

Errori comuni

  • Verificare un corpo che il framework ha già analizzato. Il middleware JSON consegna un oggetto, e serializzarlo di nuovo può cambiare i byte di TikTok; leggi il corpo grezzo sulla rotta del webhook.
  • Rispondere 200 a una consegna la cui firma non è valida. TikTok smette di inviare un evento appena riceve un 200, quindi un evento genuino rifiutato da un controllo mal configurato va perso; un 4xx lascia TikTok a riprovare per fino a 72 ore.
  • Confrontare le firme con ===, come fa l'esempio di TikTok. Un confronto a tempo costante come timingSafeEqual non rivela quanto di una firma falsa ha combaciato.
  • Decodificare in base64 il segreto di easyCoexistence o tagliarne il prefisso whsec_. La chiave HMAC è la stringa intera, esattamente come è stata mostrata una sola volta.
Farlo con EasyCoexistence

Imposta l'endpoint con set_social_webhook_destination da Claude o ChatGPT, oppure con PUT /channels/{id}/webhook. Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.

Domande frequenti

Cos'è x-tt-logid in un webhook TikTok?

Un header che riporta l'ID univoco di ogni consegna. TikTok chiede ai ricevitori di registrarlo, perché identifica la richiesta quando segnali un problema a TikTok.

TikTok invia una sfida per verificare un nuovo URL del webhook?

TikTok non ne documenta per la sua API for Business. La chiamata /business/webhook/update/ registra l'URL, e le consegne arrivano poi con Tiktok-Signature da verificare sul tuo server.

Perché la firma del mio webhook TikTok non corrisponde mai?

Controlla l'input e la chiave: l'HMAC deve coprire t, un punto e il corpo grezzo così come è arrivato, usare il segreto dell'app, ed essere confrontato con il valore dopo s= e non con l'intero header.

Come verifico gli eventi TikTok inoltrati da easyCoexistence?

Con X-EC-Signature e il segreto di firma mostrato quando imposti la destinazione: ricalcola l'HMAC-SHA256 su t, un punto e il corpo grezzo, confrontalo con v1, e rifiuta un t più vecchio di 5 minuti.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il