TikTok Events API dans n8n : tracking server-side pour vos campagnes Ads

Depuis l'introduction de l'App Tracking Transparency d'Apple et la généralisation des bloqueurs de scripts tiers, une part croissante des conversions issues d'une campagne TikTok Ads n'atteint jamais le Pixel installé sur un site : navigation privée, extension de blocage, ou simple refus du consentement de mesure. Alessandro Acquisti, Curtis Taylor et Liad Wagman, dans leur synthèse de référence The Economics of Privacy (Journal of Economic Literature, 2016), rappellent que ce durcissement des règles de collecte n'est pas un simple obstacle technique : il redistribue directement la valeur économique entre plateformes, annonceurs et utilisateurs, en réduisant la quantité de signal disponible pour mesurer l'efficacité réelle d'une campagne. Comme Meta et LinkedIn avant elle — voir notre guide de Conversions API Meta et notre guide LinkedIn Conversions API — TikTok répond à cette perte de signal avec sa propre Events API : un envoi direct depuis votre serveur, qu'aucun bloqueur côté navigateur ne peut intercepter. Ce guide montre comment construire ce pipeline dans n8n, sans dépendre d'un node dédié puisqu'il n'en existe pas.

Pourquoi l'Events API compte pour les campagnes TikTok Ads

Le Pixel TikTok, comme tout tag installé côté client, dépend entièrement de ce que le navigateur du visiteur laisse s'exécuter. Un bloqueur de publicité, l'ITP de Safari ou simplement un utilisateur qui ferme l'onglet avant le chargement complet du script suffisent à faire disparaître une conversion réelle. TikTok Ads Manager affiche un score d'Event Match Quality (EMQ) par pixel : plus les évènements remontent avec des identifiants de correspondance fiables (email, téléphone, ttclid), plus l'algorithme d'enchères optimise correctement les campagnes. Un flux server-side bien construit améliore mécaniquement ce score, puisqu'il garantit qu'un évènement de conversion arrive à TikTok même quand le canal navigateur a échoué.

Comment fonctionne la TikTok Events API

Concrètement, l'Events API est un endpoint HTTP : un POST vers https://business-api.tiktok.com/open_api/v1.3/event/track/ (vérifiez la version en vigueur dans la documentation TikTok Business au moment de l'implémentation), avec le jeton d'accès transmis dans un en-tête Access-Token — ce jeton se génère depuis l'onglet Events API du gestionnaire d'évènements, pour le pixel concerné. Le corps de la requête décrit un ou plusieurs évènements dans un tableau data[], avec notamment :

• event — CompletePayment, AddToCart, SubmitForm, ou un nom d'évènement personnalisé ;
• event_time — timestamp de l'action réelle, pas de l'envoi à l'API ;
• event_id — identifiant unique partagé avec le Pixel pour le dédoublonnage ;
• user — les identifiants de la personne, hashés (voir Étape 2) ;
• properties — value, currency (code ISO 4217), content_id, content_type, selon l'évènement.

Le dédoublonnage par event_id

Si le Pixel capture déjà une partie des conversions côté navigateur, envoyer la même conversion une seconde fois via l'Events API la ferait compter deux fois — sauf à partager un event_id identique entre les deux envois. TikTok rapproche alors les deux évènements et n'en garde qu'un pour les statistiques et l'optimisation des enchères. Comme pour la Conversions API Meta, le plus simple dans un workflow n8n est de générer cet identifiant une fois (un UUID, via le node Crypto en opération Generate — détaillé dans notre guide du node Crypto) et de le transmettre au script du Pixel côté front en même temps qu'à l'appel serveur.

Construire le workflow dans n8n

Étape 1 — Déclencher sur l'évènement de conversion réel

Le workflow démarre sur l'évènement métier qui constitue la conversion : un webhook de commande validée (voir notre guide de connexion Shopify et notre article sur l'automatisation des commandes e-commerce), ou un webhook de paiement confirmé côté Stripe comme décrit dans notre article sur les webhooks Stripe et relances de paiement. Déclenchez l'envoi sur la confirmation réelle de l'action (paiement capturé), pas sur la simple création de commande, pour ne pas polluer vos statistiques publicitaires avec des conversions jamais finalisées.

Étape 2 — Normaliser et hasher les données utilisateur

Le bloc user accepte l'email et le téléphone du client, mais uniquement sous forme hashée en SHA-256, après normalisation : minuscules, sans espaces, téléphone au format E.164. Un node Code placé juste après le déclencheur prépare ces champs :

const crypto = require('crypto');

const hash = (value) =>
  crypto.createHash('sha256').update(value.trim().toLowerCase()).digest('hex');

const email = hash($json.customer_email);
const phone = hash($json.customer_phone.replace(/[^0-9]/g, ''));

return [{ json: { ...$json, email_hash: email, phone_hash: phone } }];

Le node Crypto en opération Hash (SHA256, sortie HEX) fait exactement le même calcul sans code, si vous préférez rester sur des nodes standards. À l'inverse, l'adresse IP du client, le user-agent et l'identifiant de clic ttclid (capturé côté front, dans le paramètre d'URL au retour d'une annonce TikTok) doivent voyager en clair : les hasher les rendrait inutilisables pour le rapprochement d'identité que TikTok effectue de son côté.

Étape 3 — Construire le payload et appeler l'API

Un node Set assemble le JSON final au format attendu, puis un node HTTP Request en POST envoie la requête, avec l'en-tête Access-Token renseigné depuis un credential n8n dédié :

{
  "event_source": "web",
  "event_source_id": "{{ $json.pixel_id }}",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1755000000,
    "event_id": "{{ $json.event_id }}",
    "user": {
      "email": ["{{ $json.email_hash }}"],
      "phone": ["{{ $json.phone_hash }}"],
      "ttclid": "{{ $json.ttclid }}"
    },
    "properties": {
      "content_id": "{{ $json.product_id }}",
      "content_type": "product",
      "currency": "EUR",
      "value": "{{ $json.order_total }}"
    },
    "page": {
      "url": "{{ $json.checkout_url }}"
    }
  }]
}

Le jeton d'accès appartient à un credential n8n dédié, jamais codé en dur dans le node — la même discipline que celle décrite dans notre guide sur la sécurisation des credentials et clés API. Comme pour tout appel à une API externe, un webhook de commande qui se déclenche deux fois pour la même transaction (redélivrance réseau, double clic) doit être filtré en amont : le même principe que l'idempotence des webhooks, appliqué ici à l'envoi vers TikTok plutôt qu'au traitement métier lui-même.

Étape 4 — Vérifier avec le test_event_code

Avant de publier le workflow, ajoutez temporairement un champ test_event_code au payload — généré depuis l'onglet Events API du gestionnaire d'évènements, pour le pixel concerné. L'évènement apparaît alors en quelques secondes dans l'onglet Test Events de l'interface TikTok, avec le détail des champs reçus et les éventuels avertissements (email mal formé, event_id manquant). Une fois validé, retirez ce champ : le laisser en production exclurait l'évènement de vos statistiques réelles.

Pas de node TikTok natif dans n8n : le HTTP Request suffit

Contrairement à Meta (node Facebook Graph API) ou à des dizaines d'autres services, n8n ne propose à ce jour aucun node natif couvrant la TikTok Events API. Quelques community nodes existent pour d'autres usages (publication de vidéos, consultation de profil), mais aucun ne couvre ce cas précis. Ce n'est pas un manque bloquant : un node HTTP Request générique, avec l'en-tête Access-Token et le corps JSON décrit ci-dessus, reproduit exactement ce que ferait un node dédié — c'est d'ailleurs la même approche que celle détaillée dans notre guide des community nodes pour toute intégration qui n'a pas encore de node officiel.

Bonnes pratiques et pièges à éviter

• Ne jamais hasher l'adresse IP, le user-agent ou le ttclid — ces champs doivent rester en clair, contrairement aux identifiants personnels.
• Générer l'event_id une seule fois par conversion et transmettre exactement la même valeur au Pixel front et à l'appel serveur, sous peine de compter chaque conversion deux fois.
• Déclencher sur la confirmation réelle, pas sur la création de commande, qui peut encore être annulée ou rester impayée.
• Séparer clairement environnements de test et de production : un test_event_code oublié en production retire silencieusement de vraies conversions de vos statistiques.
• Le même schéma général — envoi server-side, identifiants hashés, dédoublonnage par identifiant partagé — s'applique presque à l'identique aux trois autres API de tracking server-side que nous avons documentées : GA4 Measurement Protocol, Meta Conversions API et LinkedIn Conversions API. Une fois le premier pipeline construit dans n8n, les suivants réutilisent la même structure de nodes avec un endpoint et un format de payload différents.

En résumé

Construire un pipeline TikTok Events API dans n8n tient en quatre briques : un déclencheur sur la conversion réelle (commande ou paiement confirmé), une normalisation et un hashing SHA-256 des identifiants personnels, un appel HTTP structuré vers l'endpoint event/track/ avec un event_id partagé avec le Pixel, et une vérification via le test_event_code avant la mise en production. Aucun node dédié n'est nécessaire — un node Webhook, un node Crypto ou Code, et un node HTTP Request suffisent. Si votre instance n8n gère déjà vos commandes e-commerce ou vos webhooks de paiement, comme le prévoient les workflows des packs FlowKit, ajouter cet envoi ne demande qu'un node de plus dans un workflow existant plutôt qu'une intégration construite de zéro.