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.
Le due parti di Tiktok-Signature: il timestamp Unix della consegna in secondi e la firma generata da TikTok per essa.
L'acceptableDelay nell'esempio Node di TikTok, che rifiuta una consegna firmata correttamente ma più vecchia di quel valore.
L'header che riporta l'ID univoco di ogni consegna, che TikTok chiede ai ricevitori di registrare per la risoluzione dei problemi.
Tipo di evento per i webhook delle menzioni, la cui guida alla sottoscrizione rimanda alla stessa verifica della firma.
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:
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: 202201120803530102451591650189C78Quali 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:
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:
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.
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