Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Vérifier les webhooks TikTok : l'en-tête de signature et comment le contrôler

L'API for Business de TikTok signe chaque envoi de webhook dans un en-tête Tiktok-Signature de la forme t=<secondes unix>,s=<hex>, où s est un HMAC-SHA256 de la valeur de t, d'un point et du corps de la requête, avec le secret de l'application développeur pour clé. Pour le vérifier, recalculez ce HMAC sur le corps brut tel que reçu, comparez-le à s en temps constant et rejetez un t périmé.

easyCoexistence vérifie la signature TikTok de chaque événement de commentaire reçu par son application, puis transfère les événements de commentaire du compte connecté vers votre endpoint HTTPS, signés dans X-EC-Signature avec un secret propre à ce seul compte.

t and s

Les deux parties de Tiktok-Signature : l'horodatage Unix en secondes de l'envoi et la signature que TikTok a générée pour celui-ci.

5 seconds

L'acceptableDelay de l'exemple Node de TikTok, qui refuse un envoi correctement signé s'il est plus ancien que ce délai.

x-tt-logid

En-tête portant l'ID unique de chaque envoi, que TikTok demande aux récepteurs de journaliser pour le dépannage.

BRAND_MENTION

Type d'événement des webhooks de mention, dont le guide d'abonnement renvoie à la même vérification de signature.

v1

La partie signature de l'en-tête X-EC-Signature d'easyCoexistence, un HMAC-SHA256 de t, d'un point et du corps brut.

À quoi ressemble l'en-tête Tiktok-Signature ?

Deux parties, séparées par une virgule : t, l'horodatage Unix en secondes de cet envoi, et s, la signature, longue de 64 caractères hexadécimaux. Les pages de TikTok écrivent le nom TikTok-Signature, Tiktok-Signature ou tiktok-signature ; les noms d'en-têtes HTTP ne tiennent pas compte de la casse, donc lisez-le sans distinction de casse, comme la plupart des frameworks le font déjà. Les autres en-têtes de l'exemple d'envoi de 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

Quels octets TikTok signe-t-il ?

La valeur de t sous forme de chaîne, un point, puis le corps. Le guide de TikTok appelle cette dernière partie une copie JSON sérialisée du corps de la requête, et son exemple Node reconstruit cette copie en appelant JSON.stringify sur un objet déjà analysé. Cela ne reproduit les octets de TikTok que si les deux sérialiseurs s'accordent sur les espaces, l'ordre des clés et l'échappement ; hachez donc le corps exactement tel qu'il est arrivé, avant qu'un middleware JSON ne le lise.

Quel secret sert de clé ?

Le secret de l'application développeur, à trouver sous My Apps, App Detail, Basic Information sur le portail développeur de TikTok. C'est la valeur que l'application envoie déjà comme secret à /business/webhook/update/ et comme client_secret aux endpoints de token. Un seul secret signe les envois de chaque compte ayant autorisé l'application ; un récepteur n'a donc besoin d'aucune clé par compte, et ni le token d'accès ni l'ID de l'application n'entrent en jeu.

Comment la vérifier en Node.js ?

Avec node:crypto et le corps brut. La fonction ci-dessous découpe l'en-tête, recalcule le HMAC sur t, le point et les octets du corps, compare le résultat en temps constant, puis contrôle l'âge de t. Elle prend en argument le nom de la partie signature, si bien que le même code vérifie aussi les envois transférés par easyCoexistence, où cette partie s'appelle v1 et où la clé est le secret de signature du compte :

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

Au bout de combien de temps refuser un envoi ?

TikTok laisse la limite au récepteur : calculez l'écart entre votre horloge et t, indique son guide, et décidez s'il est tolérable. Son exemple Node accepte 5 secondes, un seuil si serré qu'une horloge de serveur décalée de quelques secondes pourrait refuser des envois authentiques ; le code ci-dessus accepte 300 secondes, la fenêtre qu'easyCoexistence demande aux récepteurs d'appliquer à ses propres transferts. Mesurez depuis t, l'instant d'envoi que couvre la signature, et non depuis create_time dans le corps, qui marque le moment où l'événement s'est produit. Dans l'exemple de TikTok, t tombe une seconde après create_time.

Que doit renvoyer l'endpoint ?

Un 200 dès que la signature est valide, le traitement se faisant ensuite, car TikTok considère tout autre statut comme un envoi échoué et le renvoie. Pour une signature qui ne correspond pas, l'exemple de TikTok répond par un statut 4xx et journalise l'en-tête x-tt-logid, qui identifie la requête si vous signalez un problème à TikTok. client_key dans le corps désigne l'application développeur ; le comparer à votre propre ID d'application est une seconde vérification peu coûteuse.

Comment l'URL de rappel est-elle enregistrée, et est-elle vérifiée ?

Par un seul appel d'API, et TikTok ne documente aucune requête de défi qui testerait d'abord l'URL. POST /business/webhook/update/ prend app_id, le secret, un event_type et une callback_url en HTTPS : VIDEO pour les événements de publication, COMMENT pour comment.update et, sur la Mentions API, BRAND_MENTION pour brand.mention.event. Tous arrivent signés de la même manière, et GET /business/webhook/list/ affiche l'URL enregistrée pour un type d'événement. La preuve d'origine est la signature de chaque envoi.

Peut-on vérifier Tiktok-Signature sur les événements transférés par easyCoexistence ?

Non, et rien ne l'exige. TikTok signe ces envois avec le secret de l'application développeur d'easyCoexistence, qu'aucun outil ni aucune API ne fournit. easyCoexistence vérifie cette signature à l'arrivée de chaque événement, répond 401 à une signature invalide, ignore un corps dont client_key désigne une autre application, puis signe son transfert vers vous dans X-EC-Signature avec le secret de signature de ce compte connecté.

Comment easyCoexistence signe-t-il ce qu'il transfère ?

Dans l'en-tête X-EC-Signature, sous la forme t=<unix>,v1=<hex>, où t est l'heure du transfert et v1 le HMAC-SHA256 en hexadécimal de t, d'un point et du corps exactement tel qu'envoyé. La clé est le secret de signature du compte, whsec_ suivi de 32 caractères, utilisé en entier, préfixe compris. Parmi ses propres en-têtes, easyCoexistence n'envoie que Content-Type et celui-ci, sans en-tête d'événement ; lisez donc le nom de l'événement dans 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))

Que se passe-t-il quand le secret de signature est remplacé ?

Le nouveau secret signe à partir du transfert suivant. Appeler à nouveau set_social_webhook_destination ou PUT /channels/{id}/webhook renvoie un nouveau secret et retire immédiatement l'ancien ; chaque transfert n'étant envoyé qu'une seule fois, un événement que votre serveur refuse pendant le changement est perdu. Acceptez donc les deux secrets pendant quelques minutes, le temps que le nouveau soit déployé. Les événements de statut concernant les canaux et les publications utilisent un autre secret, celui affiché dans Dashboard, Profile, Developers, et arrivent avec les en-têtes X-EC-Event et X-EC-Delivery, relancés pendant environ 33 heures.

Erreurs courantes

  • Vérifier un corps que le framework a déjà analysé. Le middleware JSON remet un objet, et le sérialiser à nouveau peut modifier les octets de TikTok ; lisez le corps brut sur la route du webhook.
  • Répondre 200 à un envoi dont la signature a échoué. TikTok cesse d'envoyer un événement dès qu'il reçoit un 200, donc un événement authentique refusé par une vérification mal configurée est perdu ; un 4xx fait réessayer TikTok pendant jusqu'à 72 heures.
  • Comparer les signatures avec ===, comme le fait l'exemple de TikTok. Une comparaison en temps constant, comme timingSafeEqual, ne révèle pas combien d'une signature falsifiée correspond.
  • Décoder le secret d'easyCoexistence en base64 ou retirer son préfixe whsec_. La clé HMAC est la chaîne entière, exactement telle qu'elle a été affichée une seule fois.
Faire cela avec EasyCoexistence

Définissez l'endpoint avec set_social_webhook_destination depuis Claude ou ChatGPT, ou avec PUT /channels/{id}/webhook. De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Qu'est-ce que x-tt-logid dans un webhook TikTok ?

Un en-tête portant l'ID unique de chaque envoi. TikTok demande aux récepteurs de le journaliser, car il identifie la requête lorsque vous signalez un problème à TikTok.

TikTok envoie-t-il un défi pour vérifier une nouvelle URL de webhook ?

TikTok n'en documente aucun pour son API for Business. L'appel /business/webhook/update/ enregistre l'URL, puis les envois arrivent avec Tiktok-Signature que votre serveur doit contrôler.

Pourquoi ma signature de webhook TikTok ne correspond jamais ?

Vérifiez l'entrée et la clé : le HMAC doit couvrir t, un point et le corps brut tel que reçu, utiliser le secret de l'application, et être comparé à la valeur qui suit s= plutôt qu'à l'en-tête entier.

Comment vérifier les événements TikTok transférés par easyCoexistence ?

Avec X-EC-Signature et le secret de signature affiché lors de la définition de la destination : recalculez le HMAC-SHA256 sur t, un point et le corps brut, comparez-le à v1, et refusez un t de plus de 5 minutes.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le