Vos données, là où vous prenez la décision
Chaque identification peut atteindre vos systèmes de deux façons : poussée vers votre serveur à l'instant où elle se produit, ou récupérée par vous à la seconde exacte où vous décidez. Les deux canaux portent les mêmes chiffres — et cette partie est verrouillée par un test, pas par une promesse.
Push ou pull
Les webhooks vous poussent les événements au fur et à mesure. La Data API vous laisse demander au moment où vous avez besoin d'une réponse. La plupart des équipes utilisent les deux : les webhooks pour enregistrer et réagir, la Data API pour vérifier en ligne.
Webhooks — push, en temps réel
Nous envoyons en POST un événement JSON signé vers votre endpoint à l'instant où quelque chose se produit : un visiteur est identifié, une prise de contrôle de compte est signalée, une attaque de bots démarre. Rien à interroger en boucle, rien à planifier.
Idéal pour : enregistrer chaque visite, réagir aux attaques, alimenter votre entrepôt de données ou votre SIEM.
Latence de livraison p50 de 44–140 ms, de l'événement à votre endpoint.
Data API — pull, à la demande
Une API privée de serveur à serveur. Votre backend s'authentifie avec une clé secrète et lit exactement ce que nous savons d'un visiteur à la seconde où il décide — typiquement à l'intérieur d'un gestionnaire de connexion ou de paiement.
Idéal pour : un contrôle en ligne avant de débiter une carte, de valider une inscription ou de débloquer un compte.
Disponible à partir de l'offre Pro.
Quatre types d'événement, une seule enveloppe
Chaque livraison arrive dans la même enveloppe, avec le type d'événement dans le corps et dans l'en-tête X-Tracio-Event-Type — de sorte qu'un seul gestionnaire peut router les quatre.
Visiteur identifié
L'événement central : une visite a été évaluée. Il porte l'identifiant visiteur, le navigateur et le système d'exploitation, la géolocalisation et le réseau, le verdict bot et la décision de risque. Il est livré par phases — un événement primaire au chargement de la page, puis une phase tardive ou de correction lorsqu'une preuve plus lente change le verdict. Corrélez les phases par requestId.
identificationPrise de contrôle de compte
Le détecteur de prise de contrôle de compte s'est déclenché sur une visite : l'appareil derrière un compte connu ne ressemble plus à l'appareil qui le possède. Il arrive comme un événement à part entière, avec le contexte du compte attaché, plutôt que caché dans un corps d'identification.
account_takeoverAttaque de bots
Une vague de trafic automatisé sur votre espace de travail. Celui-ci n'a aucune visite derrière lui : c'est une alerte au niveau de l'espace de travail, les blocs de visite sont donc simplement absents du corps au lieu d'arriver comme des coquilles vides aux scores à zéro.
attack_detectedChangement de réputation
Un profil a changé de bande de réputation. Même enveloppe que l'alerte d'attaque — un événement au niveau du profil, sans visite attachée, portant la nouvelle bande et la précédente.
reputation_changedUne livraison, abrégée
Voici le corps de base. Pro ajoute la vélocité des visites ; Business ajoute les codes de motif du verdict, les signaux comportementaux, les recommandations et les données d'appareil inter-navigateurs à cette même forme — de nouveaux blocs apparaissent, les chemins existants ne bougent jamais.
{ "version": 2, "event": "identification", "eventId": "req_8f21c4:primary", "requestId": "req_8f21c4", "phase": "primary", "visitorId": "3f9a1b2c4d5e6f70", "timestamp": "2026-07-30T12:00:00Z", "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" }, "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false }, "bot": { "result": "human", "score": 12 }, "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "suspicious", "riskScore": 65.9 }}Chaque requête porte deux signatures
X-Tracio-Signature est un HMAC-SHA256 calculé sur l'horodatage de signature joint au corps brut de la requête, avec votre secret de webhook comme clé — il prouve que l'expéditeur connaît le secret que vous détenez tous les deux. X-Tracio-Signature-Ed25519 est la signature de la plateforme : vous la vérifiez avec une clé publique récupérée sur un endpoint bien connu, il n'y a donc rien de secret à stocker de votre côté. L'horodatage fait partie du contenu signé, et c'est ce qui rend une ancienne capture inutilisable pour un rejeu.
Vérifiez contre les octets bruts de la requête : re-sérialiser le JSON change les octets et la signature ne correspondra plus. Les nouvelles tentatives portent le même X-Tracio-Event-Id, dédupliquez donc dessus.
En-têtes présents sur chaque livraison
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Conçu pour ne pas perdre d'événements
La livraison tourne sur une flotte dédiée, et la source de vérité est la file d'attente, pas la mémoire d'un processus. C'est ce qui rend l'« au moins une fois » réel : si un nœud de livraison meurt en plein vol, l'événement est toujours dans la file et un autre nœud le reprend.
Des relances taillées pour de vraies pannes
5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. Les premières relances tombent dans la minute, un redémarrage bref de votre service ne vous coûte donc rien. Chaque pause est tirée au hasard entre la moitié de la valeur indiquée et la valeur pleine, pour que les relances ne reviennent pas en une seule salve après une panne.
Une désactivation automatique qui ne se déclenche pas à tort
Un webhook n'est coupé que lorsque les échecs atteignent le seuil et durent depuis au moins 15 minutes consécutives — une rafale de livraisons en file pendant un redémarrage ne tuera pas l'intégration. Un 410 Gone désactive immédiatement. Le tableau de bord affiche le motif, le code de réponse et un bouton de réactivation.
Rotation des secrets sans interruption
Après une rotation, les deux secrets restent valides pendant 24 heures et l'en-tête porte les deux signatures : une correspondance sur l'une ou l'autre suffit. Vous mettez à jour votre configuration à l'intérieur de la fenêtre au lieu de courir après une bascule ; « Révoquer maintenant » raccourcit la fenêtre quand vous avez besoin que ce soit fini.
Un journal de livraison lisible
Chaque tentative — code de réponse, durée, texte d'erreur — est visible par webhook dans le tableau de bord, à côté d'une action de test qui envoie à votre endpoint une charge utile d'exemple signée, pour que vous puissiez confirmer votre vérificateur avant de passer en production.
Demandez au moment où vous décidez
Une API privée de serveur à serveur sur api.tracio.ai. Votre backend s'authentifie avec une clé secrète et lit ses propres données. Elle n'envoie délibérément aucun en-tête CORS : une clé secrète donne accès à tout ce que contient votre espace de travail et ne doit jamais atteindre un navigateur. Disponible à partir de l'offre Pro.
| Méthode | Chemin | Retourne |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Résumé du visiteur : première et dernière apparition, nombre de visites, IP et pays uniques, navigateurs et appareils, historique de risque — plus sa session la plus récente. |
| GET | /v1/visitors/{visitorId}/sessions | Liste des sessions avec pagination par curseur et filtres par plage de dates, résultat bot et score de risque minimum. |
| GET | /v1/visitors/{visitorId}/sessions/latest | La session la plus récente sous forme d'objet unique, sans enveloppe de liste. |
| GET | /v1/sessions/{requestId} | Une session précise. Passez visitorId à côté et la recherche passe par l'index des visiteurs au lieu de tout votre historique. |
| GET | /v1/visitors/{visitorId}/velocity | Activité sur une fenêtre — 1h, 24h ou 7d : combien de visites, depuis combien d'IP, depuis combien de pays, sous combien de comptes. |
Vérifier un visiteur au moment du paiement
L'appel typique : à l'intérieur de votre gestionnaire de paiement, avant d'autoriser la carte. Une requête, une réponse, et le bloc meta indique la fenêtre que vous avez réellement obtenue — si vous demandez six mois et que votre offre en conserve 30 jours, il renvoie 30 jours et le dit.
Requête
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Réponse
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Les mêmes chiffres partout
Une visite qui obtient 65,9 dans votre tableau de bord obtient 65,9 dans la Data API et 65,9 dans le corps du webhook. Deux rendus indépendants pourraient diverger — les échelles sont la voie classique, un canal vous donnant 0,93 là où l'autre dit 93 — c'est pourquoi un test de parité construit une visite unique, la rend à travers les deux canaux et compare les champs publics sur le JSON brut. L'accord est imposé, pas affirmé.
Un conseil, pas seulement des chiffres
Les scores vous disent ce que nous avons vu. Les recommandations vous disent quoi en faire, pour les quatre décisions qui coûtent réellement de l'argent — calculées par des règles versionnées, avec le raisonnement joint.
Accepter le paiement ?
Pèse le risque, la réputation de fraude et le verdict bot avant que vous n'autorisiez une carte.
Accepter l'inscription ?
Attrape le compte jetable avant qu'il n'existe — les multi-comptes et la réputation pèsent le plus lourd ici.
Le laisser entrer ?
Se durcit automatiquement quand le détecteur de prise de contrôle de compte s'est déclenché sur la visite.
Compter la conversion ?
Sépare un vrai parrainage d'un auto-parrainage ou d'un bot incentivé.
Un vocabulaire de quatre mots
Chaque scénario reçoit l'une de quatre réponses, et avec elle la base sur laquelle elle a été émise — les axes décisifs, issus d'un vocabulaire figé : bot, risque, réputation de fraude, comportement, multi-comptes, prise de contrôle de compte, réseau, schéma d'affiliation. Vous savez toujours quel axe a fait bouger le conseil, sans jamais voir de noms de signaux, de pondérations ni de seuils.
Un calcul, trois canaux
Le même bloc de recommandations voyage dans le webhook, répond dans la Data API et s'affiche sur la fiche visiteur du tableau de bord — un seul jeu de règles, un seul résultat, aucune réconciliation de votre côté. Lisez le conseil de votre scénario plutôt que le conseil global : le global est simplement le plus strict des quatre, un résumé pour tableaux de bord et non une décision de paiement. La version des règles est livrée dans la charge utile, de sorte qu'un changement de règles est quelque chose que vous constatez, pas quelque chose que vous déduisez d'un conseil qui a bougé.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Cinq SDK côté navigateur, deux canaux côté serveur
Le côté navigateur est livré sous forme de cinq SDK : JavaScript natif, React, Vue 3, Angular et Svelte 5. Il n'y a pas de SDK côté serveur, et c'est délibéré : votre backend s'intègre en HTTP simple via des webhooks signés et la Data API. La vérification de signature tient en une douzaine de lignes face à un vecteur de référence que nous publions, et il n'y a rien de plus à maintenir à jour dans l'arbre de dépendances de votre serveur.
Questions fréquentes
Branchez-le en un après-midi
Créez un webhook dans le tableau de bord, pointez-le vers votre endpoint et cliquez sur Tester. Vérifiez la signature face à notre vecteur de référence, et le plus dur est derrière vous.