Les webhooks livrent les événements d'identification à votre serveur en temps réel.
Chaque fois qu'un visiteur est identifié, TRACIO envoie une requête HTTP POST à
l'URL de webhook que vous avez configurée. Le corps de la requête est le payload
de l'événement.
Ils sont aussi le seul canal qui livre les verdicts tardifs — ceux où le comportement d'un visiteur a prouvé qu'il était automatisé après le chargement de la page.
Configurez-les dans le tableau de bord, sous Settings → Webhooks. Les webhooks nécessitent l'offre Pro ou supérieure.
| Événement | Quand | Offre |
|---|---|---|
identification | À chaque visite — les phases primary, late et correction | Toutes |
account_takeover | Le comportement sur un compte ne correspond plus au profil de son propriétaire | Business+ |
account_assessment | L'état d'évaluation de prise de contrôle d'un compte : jugé et conforme, jugé et divergent, ou non jugé | Business+ |
attack_detected | Un pic de bots sur votre site | Business+ |
reputation_changed | La réputation d'une personne liée est passée dans une autre tranche | Business+ |
transaction_state_changed | L'issue d'une transaction que vous avez envoyée à POST /v2/transactions a changé | Business+ |
login_risk | Une évaluation de connexion par POST /v2/logins/assess s'est conclue par challenge ou review | Toutes |
trusted_device_enrolled | Un appareil a été rendu de confiance pour un compte, ou sa confiance a été renouvelée | Toutes |
trusted_device_revoked | La confiance accordée à un appareil a été révoquée — via l'API ou depuis le tableau de bord | Toutes |
affiliate_threshold_crossed | La recommandation pour un affilié s'est dégradée (none → review, none → hold, review → hold) | Toutes |
Les noms d'événements utilisent des tirets bas, jamais des points : il n'existe ni
visitor.created ni session.created.
Un webhook s'abonne à des types précis ; la valeur distincte * signifie « tous les
types, y compris ceux ajoutés par la suite ». Cinq types font exception : *
n'inclut pas account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked et affiliate_threshold_crossed — nommez chacun d'eux
explicitement. account_assessment rend compte de la couverture plutôt que d'une
détection : il arrive donc à peu près une fois par visite portant un linked_id, un
ordre de volume différent de celui des autres événements. Les types de risque de
connexion et d'affiliation n'ont de sens que pour une intégration qui appelle ces API.
Un joker défini avant l'existence de ces événements ne vaut pas consentement à les
recevoir.
Un type inconnu est rejeté avec un 400 à la création ou à la modification d'un
abonnement : une faute de frappe ne peut donc pas vous laisser un webhook qui ne se
déclenche jamais en silence.
identificationUne même visite produit jusqu'à trois livraisons qui partagent le même request_id :
primary — le verdict initial, au chargement de la page.late — enrichissement environ neuf secondes plus tard, une fois les contrôles lents arrivés.correction — une correction fondée sur le comportement (pointeur, clavier, défilement).Corrélez-les par request_id et distinguez-les par phase. La phase la plus tardive
prime : si primary disait human et que correction dit bot, c'est la seconde
qui a raison.
Ne vous fiez pas à l'ordre d'arrivée. Chaque phase est livrée indépendamment et
avec son propre calendrier de nouvelles tentatives — si primary est passé en
nouvelle tentative pendant que late a réussi du premier coup, vous les recevrez dans
l'ordre inverse. Déterminez la priorité à partir du champ phase, pas de l'heure de
réception.
Ces trois-là sont les seules phases d'un événement identification. Une autre valeur
vous parvient : account_takeover et account_assessment portent phase: "beacon",
car les deux sont levés depuis le beacon comportemental de la session.
Notez le décalage que cela crée, car il touche à l'idempotence. Une livraison
identification de production a un event_id valant exactement
<request_id>:<phase>, mais d'autres livraisons brisent cette formule. Un
account_takeover vaut <request_id>:ato — le suffixe est le littéral ato, pas la
valeur du champ phase — et un account_assessment vaut
<request_id>:ato-state-<state>. Une livraison de test envoyée depuis le tableau de
bord vaut <request_id>:test, alors que la phase de son corps indique toujours
primary — et un corps au schéma 1 n'a pas de champ phase du tout, si bien que
l'en-tête est le seul endroit où ce suffixe apparaît. Utilisez event_id directement
comme clé d'idempotence et ne le reconstituez jamais à partir de request_id et de
phase. Comparez aux valeurs que vous traitez et ignorez le reste plutôt que de
rejeter la livraison.
Certains événements n'ont pas de visite : attack_detected (niveau de l'espace de
travail), reputation_changed (niveau de la personne), transaction_state_changed
(niveau de la transaction), login_risk, trusted_device_enrolled et
trusted_device_revoked (niveau du compte) et affiliate_threshold_crossed (niveau de
l'affilié). Ils n'ont ni request_id, ni visitor_id, ni aucun des blocs browser,
geo, bot ou decision — ces clés sont tout simplement absentes, de même que
l'en-tête X-Tracio-Request-Id. account_takeover et account_assessment, en
revanche, sont produits par une visite précise et portent le corps d'identification
complet correspondant à votre offre. Si vous analysez tous les événements dans un seul
handler, vérifiez event avant de toucher aux champs de visite.
Les nouveaux webhooks utilisent la version de payload 3. Les webhooks existants en version 1 ou 2 conservent la version qu'ils ont choisie ; les deux anciens schémas sont gelés et seront supprimés le 2027-04-12. Pour migrer, sélectionnez la version 3 sur la carte du webhook dans le tableau de bord.
| Version | Statut |
|---|---|
1 | Gelée ; supprimée le 2027-04-12 |
2 | Gelée ; supprimée le 2027-04-12 |
3 | La valeur par défaut des nouveaux webhooks ; clés snake_case |
La version 3 porte les mêmes champs et les mêmes valeurs que la version 2, avec des
clés en snake_case et un version: 3 de premier niveau. L'algorithme de signature et
les en-têtes sont inchangés (X-Tracio-Payload-Version: 3). Les clés de votre propre
dictionnaire fields sont vos données et ne sont pas renommées.
| v2 | v3 |
|---|---|
eventId | event_id |
requestId | request_id |
visitorId | visitor_id |
linkedId | linked_id |
userAgent | user_agent |
network.connectionType | network.connection_type |
network.proxyDetected | network.proxy_detected |
network.realIp | network.real_ip |
bot.antidetectScore | bot.antidetect_score |
identification.matchType | identification.match_type |
identification.matchConfidence | identification.match_confidence |
identification.incognitoVisits | identification.incognito_visits |
identification.driftScore | identification.drift_score |
decision.riskScore | decision.risk_score |
decision.suspectScore | decision.suspect_score |
deviceInfo | device_info |
deviceInfo.deviceId | device_info.device_id |
deviceInfo.crossBrowser | device_info.cross_browser |
deviceInfo.linkedBrowsers | device_info.linked_browsers |
screen.colorDepth | screen.color_depth |
screen.pixelRatio | screen.pixel_ratio |
clientHints | client_hints |
clientHints.platformVersion | client_hints.platform_version |
clientHints.deviceName | client_hints.device_name |
osEnvironment | os_environment |
environment.virtualMachine | environment.virtual_machine |
spoofing.spoofedAxes | spoofing.spoofed_axes |
spoofing.anonymousBrowser | spoofing.anonymous_browser |
session.durationSeconds | session.duration_seconds |
velocity.uniqueIps | velocity.unique_ips |
velocity.uniqueLocations | velocity.unique_locations |
accountAlert | account_alert |
accountAlert.accountId | account_alert.account_id |
accountAlert.driftScore | account_alert.drift_score |
accountAssessment | account_assessment |
accountAssessment.accountId | account_assessment.account_id |
accountAssessment.profile.windowsEffective | account_assessment.profile.windows_effective |
accountAssessment.profile.oldestWindowAgeSeconds | account_assessment.profile.oldest_window_age_seconds |
attack.windowMinutes | attack.window_minutes |
attack.recentBots | attack.recent_bots |
attack.recentTotal | attack.recent_total |
personId | person_id |
reputation.overallRisk | reputation.overall_risk |
linkedAccountsCount | linked_accounts_count |
linkedVisitorsCount | linked_visitors_count |
reputationChange | reputation_change |
reputationChange.personId | reputation_change.person_id |
reputationChange.previousBand | reputation_change.previous_band |
reputationChange.visitorIds | reputation_change.visitor_ids |
reputationChange.linkedAccountsCount | reputation_change.linked_accounts_count |
{ "version": 3, "event": "identification", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:primary", // "<request_id>:<phase>" — the idempotency key "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", // visit identifier, shared by all phases "phase": "primary", "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y", "linked_id": "user-42", // your ?lid=, if you passed one "tag": "checkout", "fields": { "order_ref": "A-1029", "plan": "pro" }, // custom fields that arrived with the visit "timestamp": "2026-07-30T12:00:00Z", "url": "https://shop.example.com/checkout", "ip": "203.0.113.44", "user_agent": "Mozilla/5.0 …", "browser": { "name": "Chrome", "version": "138" }, "os": { "name": "macOS", "version": "15.5" }, "device": "desktop", "gpu": "Intel Iris Plus Graphics 655", // modèle de la carte graphique, normalisé ; absent lorsqu'il est inconnu "geo": { "country": "DE", "city": "Berlin", "lat": 52.52, "lon": 13.405, "timezone": "Europe/Berlin" }, "network": { "vpn": false, "proxy": true, "tor": false, "datacenter": true, "connection_type": "DCH", "proxy_detected": true // le trafic HTTP et le chemin réseau brut sortent par des réseaux différents }, "bot": { "result": "human", "score": 3.2 }, // human | bot | uncertain "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "real", "risk_score": 12.2 }, // real | fake | suspicious "extensions": ["metamask", "privacy_badger"] // detected browser extensions; absent when none}Les valeurs nulles et vides sont omises. Les champs de type chaîne et numériques
ayant une valeur nulle (bot.type pour un humain ou bot.antidetect_score: 0, par
exemple) sont absents du JSON — ne les rendez pas obligatoires dans vos schémas et
lisez les blocs imbriqués de manière défensive.
bot.score et decision.risk_score sont des décimaux sur une échelle 0..100
avec un chiffre après la virgule — exactement les nombres que le tableau de bord et la
Data API rapportent pour la même visite. (Dans le schéma gelé v1, ils utilisent
d'autres unités : une fraction 0..1 et 0..255 respectivement.)
bot.type est soit le nom d'un bot reconnu, soit un agent d'IA vérifié
(ai_agent:<vendor>), soit une étiquette de famille. Voir
Types de bot pour le vocabulaire — les noms internes
des contrôles ne sont jamais exposés, sur aucune offre. ai_agent:<vendor> signifie
que la requête a prouvé qu'elle provenait de l'infrastructure de cet éditeur — une
signature Web Bot Auth valide, faite avec une clé que l'éditeur publie, ou une adresse
comprise dans les plages IP que l'éditeur publie — au lieu de simplement l'affirmer
dans le user agent. Une requête qui se présente comme un agent d'IA et que contredisent
toutes les preuves publiées par l'éditeur est signalée comme impersonation.
| Champ | Type | Description |
|---|---|---|
version | number | Version du schéma de payload (3) |
event | string | Type d'événement |
event_id | string | Identifiant de la livraison — la clé d'idempotence ; unique par événement et partagé par tous vos webhooks qui le reçoivent, stable d'une nouvelle tentative à l'autre |
request_id | string | Identifiant de la visite (UUID), partagé par toutes ses phases |
phase | string | primary, late, correction ; account_takeover et account_assessment portent beacon |
visitor_id | string | Identifiant de visiteur stable |
linked_id | string | Identifiant lié fourni par le client |
tag | string | Étiquette personnalisée fournie par le client |
fields | object | Champs personnalisés attachés à la visite au moment de la collecte. Uniquement ce qui est arrivé avec la visite — un champ attaché plus tard via la Data API n'apparaît jamais dans un webhook, à aucune phase ni nouvelle tentative. Les clés et les valeurs sont des chaînes. Absent lorsque la visite ne portait aucun champ |
timestamp | string | Heure de l'événement (RFC 3339) |
url | string | URL de la page où l'événement a été capturé |
ip | string | Adresse IP du client |
user_agent | string | Chaîne user-agent brute du client |
browser.name / .version | string | Navigateur détecté |
os.name / .version | string | Système d'exploitation détecté |
device | string | Classe d'appareil (p. ex. desktop, mobile) |
gpu | string | Modèle de la carte graphique tel que le navigateur le rapporte (WebGL), normalisé en un nom lisible (Intel Iris Xe Graphics, Apple M1 Pro) ; Software renderer pour les rastériseurs logiciels ; absent lorsqu'il est inconnu |
geo | object | Géolocalisation par IP : country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (booléens) et connection_type |
network.proxy_detected | boolean | Le trafic HTTP de la visite et ses chemins réseau bruts sortent par des réseaux différents — un proxy ou un VPN devant le navigateur. Deux adresses du même opérateur (NAT opérateur, une seconde sortie du même VPN) ne comptent pas |
bot.result | string | human, bot ou uncertain |
bot.type | string | Nom du bot, agent d'IA vérifié ou étiquette de famille lorsqu'un bot est détecté |
bot.score | number | Score de bot (0–100) |
identification.confidence | number | Confiance de l'identification (0.0–1.0) |
identification.incognito | boolean | Contexte de navigation privée |
decision.action | string | real, fake ou suspicious |
decision.risk_score | number | Score de risque agrégé (0–100) |
extensions | array | Extensions de navigateur détectées lors de cette visite, sous forme de slugs machine stables (les noms, catégories et liens vers les boutiques sont dans le tableau de bord et la Data API). Absent lorsque rien n'a été détecté |
Pro et au-delà — comment le visiteur se comporte dans la durée :
{ "identification": { "match_type": "exact", // exact | fuzzy | new — how the visitor was recognized "match_confidence": 0.93, "visits": 42, "incognito_visits": 3 }, // Present when visitor counters are available at event time (usually primary). // A missing block means "no data", not "zeros". "velocity": { "events5m": 7, "unique_ips": 2, "unique_locations": 1 }, "bot": { "antidetect_score": 0 }, // antidetect indicators, 0..100 "session": { "duration_seconds": 95 } // the correction phase and the account_takeover alert}Business et au-delà — pourquoi le verdict est ce qu'il est :
{ "reasons": [ // at most 8, sorted by importance { "code": "headless_browser", "severity": "high" }, { "code": "privacy_hardening", "severity": "low" } ], // Behavioral biometrics — present only when behavioral scoring ran for the // visit. A missing block means "no data", never "nothing suspicious". "behavior": { "score": 87, "verdict": "human", "confidence": 0.92 }, // The smoothed behavior score the account-takeover verdict was made on. It is // measured by beacons that arrive after the identification event, so it is // empty in identification deliveries — see the account_takeover event. "identification": { "drift_score": 0.41 }, "device_info": { "device_id": "…", // the physical device across browsers on it "cross_browser": true, "confidence": 0.88, "linked_browsers": 3 }, "network": { "isp": "Deutsche Telekom", "asn": 3320, // l'adresse publique observée sur le chemin réseau brut, c'est-à-dire // l'adresse derrière le proxy ou le VPN ; absente lorsqu'aucune adresse de // ce type n'a été observée "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // L'environnement de bureau MESURÉ sur une machine Linux ("Mint 22+", // "Ubuntu", "GNOME", "KDE") ; un User-Agent ne peut pas exprimer une // distribution. Absent lorsqu'il n'est pas déterminé — pour la plupart des // visites Linux, et pour toutes les autres. "os_environment": "Mint 22+", // Ce que la visite a prétendu d'elle-même face à ce que des contrôles // indépendants ont mesuré. Présent uniquement lorsqu'une falsification a // réellement été détectée ; un champ `real` vide signifie "le contrôle est // resté muet", jamais "confirmé". Sur l'axe `gpu`, `claimed.gpu` porte la // carte annoncée sous le même nom de modèle lisible que le champ `gpu` de // premier niveau. "spoofing": { "detected": true, "claimed": { "os": "Windows 10", "browser": "Chrome 139.0" }, "real": { "os": "macOS" }, "spoofed_axes": ["os", "screen"], // os | gpu | screen | network | browser "anonymous_browser": { "detected": true, "names": ["Linken Sphere"] } }, // Faits sur l'appareil — ce que le navigateur du visiteur rapporte de la // machine, assaini de notre côté. screen : résolution, profondeur de // couleur et device pixel ratio. locale : les langues préférées et le // fuseau horaire du navigateur lui-même — par opposition à geo.timezone, // dérivé de l'adresse IP ; un écart entre les deux est un signe courant de // localisation falsifiée. client_hints : User-Agent Client Hints — // architecture et bitness du processeur, modèle de l'appareil (Android : le // code de modèle dans `model`, par ex. "SM-A556B", et son nom commercial // issu de la liste d'appareils Google Play dans `device_name`, par ex. // "Samsung Galaxy A55 5G") et la version exacte de la plateforme ; seuls // les navigateurs basés sur Chromium les rapportent. Chaque bloc est // absent lorsque la visite ne portait pas ces données : traitez donc // chacun comme facultatif. "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 }, "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" }, "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "15.5.0" }, // Présent uniquement lorsque la carte graphique s'est déclarée virtuelle ; // hypervisor est un dictionnaire fermé (vmware, virtualbox, parallels, // qemu, hyperv, bochs, intel-gvt, vgpu). Un bloc absent signifie qu'il // n'existe aucun indice de ce type. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}Voir Détection des bots pour le vocabulaire
des codes de motif et la signification de severity.
Champs de multicompte (Business et au-delà). Une fois le mode personne activé pour
votre espace de travail, le corps porte aussi person_id, un bloc reputation
(score, categories, overall_risk), linked_accounts_count et
linked_visitors_count — pour indiquer si le visiteur est lié à d'autres visiteurs et
comptes. La couche personne fonctionne actuellement en mode observation, et tant
qu'elle n'est pas en service, ces champs sont absents du corps. Ne les rendez pas
obligatoires dans vos schémas.
guidance porte des recommandations « quoi faire » prêtes à l'emploi par point
d'intégration, pour que vous n'ayez pas à déduire une politique de scores bruts. Il
est présent dans chaque événement v3 Business+ — allow est indiqué explicitement :
{ "guidance": { "version": 3, "overall": "review", // the strictest advice across the scenarios "payment": "review", // whether to accept the payment "registration": "challenge", // whether to create the account "login": "challenge", // whether to let them into the account "affiliate": "review", // whether to credit the conversion to the partner "basis": ["risk", "network"] // the axes that determined the advice }}Chaque scénario démarre à allow et ne peut que monter dans l'échelle :
allow → challenge → review → deny. Au sein d'un scénario, l'axe le plus strict
qui se déclenche l'emporte, et overall est le plus strict des quatre scénarios.
| Recommandation | Paiement | Inscription | Connexion | Affiliation |
|---|---|---|---|---|
allow | Traitez-le | Créez-le | Laissez entrer | Créditez la conversion |
challenge | 3-D Secure / confirmation | Captcha, confirmation par e-mail ou SMS | 2FA renforcée, ré-authentification | Marquez comme douteuse jusqu'à voir de l'activité |
review | Traitez, mais mettez en file de revue | Créez avec des restrictions | Laissez entrer et levez une alerte | Retenez le paiement jusqu'à revue |
deny | Ne traitez pas la transaction | Refusez la création du compte | Ne laissez pas entrer | Ne créditez pas la conversion |
basis liste les axes qui ont déterminé la recommandation — un axe dont la
proposition était plus douce que celle retenue n'y figure pas. Lisez-le par code
plutôt que de supposer un ensemble fixe :
Axe (basis) | Ce que cela signifie |
|---|---|
list | Le visiteur correspond à l'une des listes de votre espace de travail en mode enforce. Une liste allow prime sur tous les axes : chaque scénario devient allow et basis vaut exactement ["list"] |
rule | La visite correspond à l'une des règles de votre espace de travail en mode enforce ; une règle ne déplace que la recommandation de son propre scénario (une règle allow n'adoucit que celui-ci), et elle est ignorée lorsqu'une liste a déjà agi |
bot | Le détecteur de bots a conclu à une automatisation — refuse tous les scénarios |
risk | La décision et le score de risque global de la visite |
behavior | La biométrie comportementale indique un bot avec une confiance suffisante — ajoute de la friction plutôt qu'un refus |
account_takeover | Le comportement sur ce compte ne correspond plus au profil de son propriétaire — connexion en challenge, paiement en review |
network | Tor, ou un VPN sortant d'un datacenter |
affiliate_pattern | La forme des parrainages auto-générés — la conversion affiliée est retenue en challenge |
fraud_reputation, multiaccounting | La réputation et le regroupement de comptes de la personne derrière le visiteur ; apparaissent une fois la couche personne en service |
version est la version du jeu de règles — elle est incrémentée à mesure que la
logique s'améliore : conservez-la donc dans vos journaux. La version 2 a introduit
l'axe list, le premier capable d'adoucir une recommandation ; la version 3 a placé
les seuils de connexion de account_takeover sur l'échelle du score de verdict de
prise de contrôle de compte, si bien que la même visite peut obtenir deny là où la
version 2 donnait challenge, et inversement.
Guidance est additif : les nouveaux scénarios arrivent sous forme de nouvelles clés
sans casser le contrat. La phase la plus tardive l'emporte, sauf pour les
recommandations partielles : une livraison calculée sur un ensemble d'entrées
incomplet est marquée "partial": true, et une recommandation partielle ne remplace
pas une recommandation complète reçue plus tôt pour le même request_id. Dans une
livraison ordinaire, le champ partial est totalement absent.
Les seuils exacts ne sont délibérément pas documentés. Une recommandation qui peut
être rétro-analysée jusqu'à un score cesse d'être une défense. Il existe exactement
une exception délibérée : account_assessment.verdict.threshold, la frontière de
décision du verdict de prise de contrôle de compte décrite ci-dessous.
account_takeoverBusiness et Enterprise uniquement ; sur les offres inférieures, aucune livraison n'est
créée, même si un webhook est abonné à cet événement. Le corps est l'enveloppe
d'identification complète correspondant à votre offre, plus un bloc account_alert et
le bloc account_assessment décrit dans la section suivante, livré au plus une fois
par visite :
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // l'alerte est levée depuis un beacon ; seul l'event_id dit "ato" "account_alert": { "type": "behavior-drift/2", // kind of alert and the version of its construction "account_id": "user-42", // your linked_id for the account "drift_score": 0.71 // the value the verdict was made on }, "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "assessed_alert", "verdict": { "severity": "high", "score": 0.71, "threshold": 0.3565, "scale": "manhattan-normalized", "basis": "ring", "windows": 9 }, "profile": { "windows": 6, "windows_effective": 5, "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}Pourquoi type porte une version. La construction derrière le score a déjà changé
par le passé : l'échelle et la base du verdict. behavior-drift/2 est la première
construction versionnée. Si vous avez calibré vos propres règles sur ce nombre,
considérez un changement de cette valeur comme un signal pour les revérifier.
account_alert.drift_score et identification.drift_score sont le même nombre
(depuis le 2026-10-03) : le score comportemental lissé sur lequel le verdict a été
rendu, mesuré par rapport à l'anneau des fenêtres de confiance passées du
propriétaire du compte. Avant cette date, identification.drift_score portait une
distance brute sur une autre échelle — ne mélangez pas les valeurs de part et d'autre
de cette date. Lorsqu'une fenêtre n'a pas été jugée, le champ est absent plutôt que
nul. Utilisez account_assessment.verdict lorsque vous avez besoin du nombre
accompagné du seuil auquel il a été comparé.
En v1, le bloc est accountAlert avec type, linkedId et drift, et il n'y a pas
de bloc d'évaluation. En v2, l'alerte renomme deux champs — linkedId → accountId
et drift → driftScore — et ajoute accountAssessment ; la v3 utilise les noms
snake_case ci-dessus. Mettez à jour votre handler lorsque vous changez de version,
sinon votre logique de prise de contrôle de compte cessera silencieusement de voir les
données.
account_assessmentBusiness et Enterprise uniquement. Exige un abonnement explicite : * ne l'inclut
pas.
Sans cet événement, l'absence d'alerte signifie deux choses différentes à la fois : soit nous avons évalué la session par rapport au profil du propriétaire du compte et elle correspondait, soit nous n'avons pas pu l'évaluer du tout — le profil du propriétaire n'est pas prêt, la fenêtre était trop clairsemée, ou le trafic ne venait pas d'une personne. Les deux ressemblent à du silence, et le silence se lit comme de la sécurité. Ce n'en est généralement pas : sur une journée de production complète en septembre 2026, nous nous sommes abstenus de rendre un verdict sur 73 % des fenêtres et 80 % des comptes. Un processus bâti sur « pas d'alerte, donc tout va bien » repose sur un état dont nous ne disposons le plus souvent pas.
{ "version": 3, "event": "account_assessment", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato-state-not_assessed", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "not_assessed", // always present, one of three values "reason": "profile_not_ready", // only when state is not_assessed "profile": { "windows": 3, // windows in the owner's reference ring "windows_effective": 2, // of those, how many yielded a distance "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}state n'est jamais absent ni vide :
state | Signification | Que faire |
|---|---|---|
assessed_clear | Jugé ; le comportement correspond au propriétaire | Rien |
assessed_alert | Jugé ; le comportement diverge | Authentification renforcée (step-up) — l'alerte account_takeover porte le même verdict |
not_assessed | Aucun verdict n'a été rendu | Ne pas traiter comme sain ; se rabattre sur vos propres signaux |
reason (uniquement avec not_assessed) :
reason | Signification |
|---|---|
profile_not_ready | La référence du propriétaire ne peut actuellement pas produire de verdict pour ce compte. Traitez-le comme un état, pas comme une étape : il peut ne jamais changer, donc n'attendez pas |
profile_learning | La référence est encore en cours d'accumulation |
window_too_sparse | Une personne était présente, mais la fenêtre portait trop peu d'interactions |
not_computable | La fenêtre et la référence n'avaient aucun axe informatif en commun |
bot_traffic | Les données étaient suffisantes, et il n'y avait aucune personne à juger |
Depuis le 2026-10-04 18:00 UTC, window_too_sparse et not_computable ne sont plus
émis pour un propriétaire dont la référence est prête — une telle fenêtre est signalée
comme profile_not_ready. Les deux motifs restent dans la liste parce que des
livraisons antérieures les portent : si votre handler bifurque sur eux, routez
profile_not_ready de la même façon, et ne comparez pas les taux de ces motifs de part
et d'autre de cette date.
state et reason ne dépendent pas de l'offre. verdict est réservé à Business+,
comme drift_score.
Le bloc verdict n'est présent qu'avec assessed_clear et assessed_alert. Avec
not_assessed, le bloc est absent plutôt que rempli de zéros — un score de 0 à côté
d'un threshold de 0 se lirait comme « le comportement correspondait exactement ».
| Champ | Signification |
|---|---|
severity | low ou high — deux tranches, délibérément : une tranche intermédiaire exigerait un second seuil sur la même échelle |
score | La valeur sur laquelle le verdict a été rendu |
threshold | La valeur à laquelle il a réellement été comparé |
scale | Comment le score est construit : manhattan-normalized vaut d/(1+d) dans un espace comportemental normalisé, où 0 signifie une correspondance exacte |
basis | ring — distance à la plus proche des fenêtres de confiance passées du propriétaire ; centroid — distance à son profil moyenné |
windows | Combien de fenêtres ont été agrégées dans le score |
score et threshold sont toujours sur la même échelle nommée, de sorte que la paire
reproduit la décision : l'alerte se déclenche exactement lorsque score > threshold.
À quelle fréquence il arrive. Au plus une livraison par état et par visite — en
pratique une par visite portant un linked_id, et non une par fenêtre
comportementale. Un état peut changer au sein d'une même visite — par exemple, la
référence termine son apprentissage et not_assessed devient assessed_clear — et
vous recevez alors les deux, dans l'ordre. Cette transition est possible, pas promise :
profile_not_ready peut persister pendant la vie entière du compte.
Ce qu'il ne promet pas. Les comptes les mieux protégés sont ceux d'utilisateurs actifs aux sessions longues et au profil de référence complet ; les moins bien protégés sont ceux d'utilisateurs peu fréquents, pour qui une prise de contrôle est plus dangereuse. C'est une propriété de la construction, pas un seuil réglable. L'événement signale une divergence comportementale par rapport à une référence — il ne prétend pas détecter la prise de contrôle de compte en général.
attack_detectedL'alerte de pic de bots arrive dans l'enveloppe v3 commune avec un bloc attack. Elle
n'a aucun champ d'identification — c'est un événement au niveau de l'espace de
travail :
{ "version": 3, "event": "attack_detected", "event_id": "c0a8e1f2-…", // alert id; matches X-Tracio-Event-Id "timestamp": "2026-07-30T12:00:00Z", "attack": { "kind": "bot_spike", "severity": "critical", // warning | critical "window_minutes": 15, "recent_bots": 4210, "recent_total": 5100, "expected": 180.5 // the baseline expected over a window this size }}Les webhooks en version de payload 1 reçoivent le schéma d'alerte plat historique — il ne change pas.
login_risk, trusted_device_enrolled et trusted_device_revokedCes trois événements proviennent de vos propres appels à l'API de risque de connexion
(POST /v2/logins/assess) et à ses appareils de confiance. Ils ne sont livrés que sur
abonnement explicite par nom — * ne les inclut pas — et uniquement aux webhooks
en version de payload 2 ou 3 ; la version 1 n'a pas de corps pour eux.
login_risk est envoyé lorsqu'une évaluation renvoie challenge ou review —
jamais sur allow, deny ou not_assessed. Son bloc login_risk est l'évaluation
enregistrée, exactement telle que la réponse synchrone l'a donnée. Identifiant
d'événement : login-risk:<id>, où <id> est notre identifiant de l'enregistrement
stocké — prenez votre propre assessment_id dans le corps.trusted_device_enrolled et trusted_device_revoked sont envoyés à chaque
inscription, renouvellement et révocation d'un appareil de confiance. Leur bloc
trusted_device — user_id, device_ref, enrolled_at, expires_at,
revoked_at, revoked_by (api ou dashboard) — est un instantané au moment de
l'événement ; avec trusted_device_enrolled, revoked_at et revoked_by valent
null. Identifiant d'événement : trusted-device:<n>.Ils sont envoyés de manière asynchrone, jusqu'à environ cinq secondes après l'appel, et
ne portent pas d'en-tête X-Tracio-Request-Id — utilisez login_risk.request_id pour
retrouver la visite. Le webhook est une notification destinée à l'audit et aux
alertes ; la décision elle-même est la réponse synchrone.
{ "version": 3, "event": "login_risk", "event_id": "login-risk:4b1f9e2c-6d3a-4f80-9b7e-2a5c8d1e0f37", "timestamp": "2026-10-17T10:00:00Z", "login_risk": { "assessment_id": "snap-1", "user_id": "alice", "state": "assessed", "recommendation": "challenge", "reasons": ["new_device"] // …the rest of the assessment }}{ "version": 3, "event": "trusted_device_revoked", "event_id": "trusted-device:7", "timestamp": "2026-10-17T11:00:00Z", "trusted_device": { "user_id": "alice", "device_ref": "7978151c54e94838", "enrolled_at": "2026-10-17T10:00:00Z", "expires_at": "2026-11-16T10:00:00Z", "revoked_at": "2026-10-17T11:00:00Z", "revoked_by": "dashboard" }}affiliate_threshold_crossedLivré uniquement sur abonnement explicite par nom — * ne l'inclut pas — et
uniquement aux webhooks en version de payload 2 ou 3. Toutes les 15 minutes, TRACIO
recalcule le score de qualité de chaque affilié disposant de suffisamment de données et
envoie l'événement lorsque sa recommandation se dégrade : none → review,
none → hold ou review → hold. Une amélioration n'envoie rien et permet de signaler
à nouveau la dégradation suivante. L'événement appartient à l'espace de travail : il
part vers les webhooks abonnés de chaque environnement et ne porte pas d'en-tête
X-Tracio-Request-Id. Identifiant d'événement :
affiliate-threshold:<affiliate_id>:<recommendation>:<unix time>.
{ "version": 3, "event": "affiliate_threshold_crossed", "event_id": "affiliate-threshold:aff_17:review:1792490400", "timestamp": "2026-10-20T10:00:00Z", "affiliate_threshold": { "affiliate_id": "aff_17", "recommendation": "review", // none | review | hold "previous_recommendation": "none", "quality_score": 72, // 0..100, higher is better "hold_days": 14, // the current hold period of the workspace "crossed_at": "2026-10-20T10:00:00Z", "metrics": { "reg_to_ftd": 0.31, "active14_share": 0.42, "dup_device_share": 0.3, "dup_person_share": 0.1, "ring_share": 0.05, "bonus_hunter_share": 0.2, "dc_vpn_bot_share": 0.1, "chargeback_share": 0.03, "affiliate_fraud_share": 0, "no_visit_share": 0.05 } }}metrics sont les parts de l'affilié sur les 90 derniers jours, les mêmes que celles
du rapport du tableau de bord : la part des inscriptions ayant atteint un premier dépôt
(reg_to_ftd), la part des joueurs encore actifs 14 jours après l'inscription
(active14_share), et les parts des conversions avec un appareil ou une personne en
double, issues d'un réseau de fraude, de chasseurs de bonus, d'un datacenter, d'un VPN
ou d'un bot, marquées comme rétrofacturation (chargeback) ou comme fraude d'affilié, et
sans visite trouvée. TRACIO ne fait que recommander — la retenue elle-même et les
décisions de paiement restent dans votre plateforme d'affiliation. En version de
payload 2, le même corps a des clés en camelCase : le bloc est affiliateThreshold,
avec affiliateId, previousRecommendation, qualityScore, etc.
transaction_state_changedBusiness et au-delà. Envoyé lorsque l'issue d'une transaction que vous avez envoyée à
POST /v2/transactions change : les règles ont décidé REVIEW ou DECLINE (un
APPROVE n'envoie rien), un analyste a envoyé la transaction en revue dans le tableau
de bord, ou une étiquette a été posée, remplacée ou retirée. Utilisez-le pour retenir
un bonus pendant qu'une demande est en revue, puis le refuser ou le libérer une fois
l'issue établie, sans polling. * inclut cet événement ; il n'est livré qu'aux
webhooks en version de payload 2 ou 3. Un webhook lié à un environnement ne le reçoit
que pour cet environnement.
{ "version": 3, "event": "transaction_state_changed", "event_id": "txn-state:7d1c2b3a-0000-4000-8000-000000000042:118", "timestamp": "2026-10-15T10:04:00Z", "transaction": { "id": "7d1c2b3a-0000-4000-8000-000000000042", "transaction_id": "bonus-claim-1842", "state": "REVIEW", // always the decision of the rules "fraud_score": 50, "effective_state": "DECLINE", // the outcome to act on "recommendations": ["withhold_bonus"], "label": "fraud_detection_bonus_abuse", "label_source": "api", // api | dashboard "label_at": "2026-10-15T10:04:00Z", "previous_effective_state": "REVIEW" // …applied_rules and evidence, as in the transaction response }}| Clé | Signification |
|---|---|
effective_state | L'issue sur laquelle agir : l'état fixé par l'analyste ou par l'étiquette lorsqu'il y en a un, sinon state |
recommendations | Que faire du bonus, dérivé de effective_state |
label, label_source, label_at | L'étiquette actuelle, où elle a été posée (api ou dashboard) et quand ; les trois valent null lorsque la transaction n'a pas d'étiquette |
previous_effective_state | effective_state avant ce changement ; null pour l'événement envoyé sur la décision automatique |
Le bloc montre la transaction telle qu'elle est au moment de l'envoi de
l'événement : si deux changements se suivent rapidement, les deux événements portent
le dernier état, chacun avec son propre previous_effective_state et son propre
timestamp. L'ordre n'est pas garanti — triez par timestamp, et lisez la
transaction via l'API pour connaître son état actuel. Identifiant d'événement :
txn-state:<id>:created pour la décision automatique et txn-state:<id>:<n> pour
chaque changement ultérieur. L'événement ne dit pas qui a posé une étiquette —
seulement d'où elle vient.
reputation_changedBusiness et au-delà. Envoyé lorsque la réputation inter-clients d'une personne que
votre organisation a vue passe dans une autre tranche (clean → suspicious, par
exemple). Il nécessite la couche personne, qui fonctionne actuellement en mode
observation — l'événement ne se déclenche donc que pour les espaces de travail où la
résolution d'identité entre appareils est activée. C'est un événement au niveau de la
personne : il n'a ni request_id ni blocs de visite.
{ "version": 3, "event": "reputation_changed", "event_id": "person-reputation:pn_4f2a…:clean->suspicious:2026-07-30T12:10:00.123456Z", "timestamp": "2026-07-30T12:10:00Z", "reputation_change": { "person_id": "pn_4f2a…", "score": 46, "band": "suspicious", // clean | suspicious | fake "previous_band": "clean", "categories": ["chargeback"], "visitor_ids": ["X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"], // the person's visitors in YOUR data "linked_accounts_count": 4 // omitted when zero }}La clé du bloc est reputation_change, et non reputation : cette dernière désigne
la réputation dans le contexte d'une visite précise, et les deux sont des choses
différentes. Le schéma 1 livre la forme plate historique — les mêmes champs au premier
niveau.
Chaque livraison inclut un en-tête X-Tracio-Signature :
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t est l'horodatage Unix (en secondes) auquel la requête a été signée.v1 est le HMAC-SHA256 encodé en hexadécimal de "<t>.<rawRequestBody>", avec
votre secret de webhook comme clé.L'horodatage fait partie du contenu signé, ce qui apporte une protection contre le rejeu.
Deux points à ne pas manquer, sinon la vérification échoue en production :
v1=. Pendant une
rotation de secret, l'en-tête porte deux signatures, et un parseur qui n'en
conserve qu'une rejettera des livraisons valides pendant toute la fenêtre de
rotation.// Express.js exampleimport express from "express"import crypto from "crypto"
const app = express()
// Capture the raw body so the signature can be verified byte-for-byte.app.use( express.json({ verify: (req, _res, buf) => { ;(req as any).rawBody = buf }, }),)
function verifySignature(rawBody: Buffer, header: string, secret: string): boolean { if (!header) return false
const parts = header.split(",").map((p) => p.trim()) const ts = parts.find((p) => p.startsWith("t="))?.slice(2) if (!ts) return false
// Replay protection: reject timestamps more than five minutes old. if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
// Sign the raw bytes: the "<t>." prefix plus the raw request body. const signed = Buffer.concat([Buffer.from(`${ts}.`, "utf8"), rawBody]) const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex") const exp = Buffer.from(expected, "hex")
// During a rotation window the header carries several v1= — any may match. return parts.some((p) => { if (!p.startsWith("v1=")) return false const got = Buffer.from(p.slice(3), "hex") // Compare lengths BEFORE timingSafeEqual: it throws on differing lengths, // and one junk header would turn the handler into a 500. return got.length === exp.length && crypto.timingSafeEqual(got, exp) })}
app.post("/webhook/tracio", (req, res) => { const header = req.headers["x-tracio-signature"] as string if (!verifySignature((req as any).rawBody, header, WEBHOOK_SECRET)) { return res.status(401).json({ error: "Invalid signature" }) }
const event = req.body console.log(`Visitor: ${event.visitor_id}`) console.log(`Bot: ${event.bot?.result}`) // "human" | "bot" | "uncertain"
res.status(200).send("OK")})Les livraisons aux schémas 2 et 3 portent en plus X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Les deux parties connaissent le secret HMAC : le
HMAC prouve donc que l'expéditeur connaît le secret, mais pas que la requête émane de
TRACIO ; la signature asymétrique, si. Les clés publiques sont publiées sur
https://api.tracio.ai/.well-known/webhook-keys, indexées par kid : lisez le champ
public_key. L'alias historique publicKey porte la même valeur et sera supprimé le
2027-04-12.
Les livraisons de test envoyées depuis le tableau de bord sont signées en HMAC
uniquement — la clé privée de plateforme réside sur les nœuds de livraison et n'est
délibérément pas accessible au tableau de bord. Un vérificateur qui exige
strictement Ed25519 doit laisser passer les livraisons de test (elles portent un
suffixe :test sur event_id), faute de quoi les tests depuis le tableau de bord
échouent alors que la production se porte bien. La même prudence vaut pour les
contrôles de format : une livraison de test porte un request_id de la forme
test_<hex> et le littéral test_visitor comme visitor_id, si bien qu'un handler
qui les valide contre les formes de production rejettera une livraison par ailleurs
parfaitement formée.
Après une rotation, les deux secrets restent valides pendant 24 heures et l'en-tête porte les deux signatures : vous pouvez donc mettre à jour votre configuration sans perdre de livraisons. L'action Revoke now écourte la fenêtre. Mettez à jour le secret de votre côté dans les 24 heures : une fois la fenêtre fermée, l'ancien secret cesse de correspondre, et si votre endpoint répond à une signature invalide par un 4xx, cinq réponses de ce type d'affilée désactivent le webhook.
| En-tête | Description |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — deux v1= pendant une fenêtre de rotation |
X-Tracio-Signature-Ed25519 | Signature de plateforme, t=<unix>,kid=<id>,v1=<base64> (v2 et v3 uniquement) |
X-Tracio-Event-Id | Identifiant de la livraison — la clé d'idempotence |
X-Tracio-Request-Id | Identifiant de la visite, correspond à request_id (v2 et v3 uniquement). Envoyé uniquement pour les événements de visite — identification, account_takeover et account_assessment |
X-Tracio-Event-Type | Le type d'événement (v2 et v3 uniquement) |
X-Tracio-Delivery-Attempt | Numéro de tentative, à partir de 1 (v2 et v3 uniquement) |
X-Tracio-Payload-Version | 3 ou 2 (v2 et v3 uniquement) |
X-Tracio-Webhook-Id | Identifiant du webhook qui a produit cette livraison |
Les livraisons peuvent faire l'objet de nouvelles tentatives, et une nouvelle
tentative porte le même X-Tracio-Event-Id. Dédupliquez dessus :
app.post("/webhook/tracio", async (req, res) => { const eventId = req.headers["x-tracio-event-id"] as string
const existing = await db.webhooks.findOne({ eventId }) if (existing) return res.status(200).send("Already processed")
await db.webhooks.insert({ eventId, processedAt: new Date() }) await processWebhookEvent(req.body)
res.status(200).send("OK")})Notez que event_id est unique par événement, et non par webhook : si plusieurs
webhooks de l'espace de travail sont abonnés au même événement, chacun reçoit une
livraison portant le même identifiant. Pour identification, il se construit comme
<request_id>:<phase>, c'est pourquoi les trois phases d'une visite se dédupliquent
indépendamment au lieu de se confondre en une seule. Les événements sans visite ont
leurs propres formes — voir chaque événement ci-dessus.
Répondez par un 2xx — c'est le seul signe qu'une livraison a été acceptée.
| Réponse | Ce qui se passe |
|---|---|
2xx | Livraison terminée |
429 Too Many Requests | N'est pas comptée comme un échec et ne consomme pas de tentative ; un Retry-After plus long est respecté |
408, 425, 5xx, connexion coupée | Nouvelle tentative avec une pause croissante |
410 Gone | L'endpoint est considéré comme supprimé — le webhook est désactivé immédiatement |
Autres 4xx | Nouvelle tentative, mais cinq d'affilée désactivent le webhook — 400/401/404 ne se corrigent pas en réessayant |
Calendrier des nouvelles tentatives : 5 s → 30 s → 2 min → 10 min → 30 min → 2 h → 6 h (8 tentatives). Les premières tiennent dans la minute : un redémarrage bref de votre service ne vous coûte donc pas une notification. Chaque pause est randomisée entre la moitié et la valeur complète, afin que les tentatives ne repartent pas toutes en même temps après une panne.
La désactivation automatique exige à la fois un seuil (20 échecs consécutifs, ou 5 erreurs de configuration) et au moins 15 minutes consécutives d'échecs — un redémarrage bref ne peut pas tuer l'intégration, même si de nombreuses livraisons étaient en file. Un intervalle de plus de 15 minutes remet le compteur à zéro. Le tableau de bord affiche la raison, avec le code de réponse et le texte de l'erreur, ainsi qu'un bouton Re-enable qui réinitialise les compteurs.
| Offre | Webhooks par espace de travail |
|---|---|
| Free | Non disponible |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Les endpoints doivent être en https avec une IP publique — les adresses privées et
de loopback sont rejetées, y compris lors d'une redirection — et ne pas dépasser deux
redirections de profondeur.
Seules les redirections 307 et 308 sont suivies. 301, 302 et 303
demandent au client de basculer en GET et d'abandonner le corps : une livraison ne les
suit donc pas et la tentative est comptée comme échouée. Si votre répartiteur de charge
normalise l'URL (en ajoutant www ou une barre oblique finale), faites pointer le
webhook directement sur l'URL finale.
Les webhooks se gèrent dans le tableau de bord. Celui-ci s'appuie sur une API de
gestion à portée d'espace de travail, servie sur l'hôte de l'application (par exemple
https://app.tracio.ai/api/v1), et les endpoints ci-dessous sont exactement ceux qu'il
appelle. Tous les endpoints de webhook se trouvent sous /workspaces/{wsId}.
Ce n'est pas une surface serveur à serveur. L'API de gestion n'accepte que le JWT de votre session de tableau de bord, contrôlé par rapport à votre rôle dans l'espace de travail (RBAC) ; une clé secrète
tracio_sk_…y est refusée. Comme cette session vit dans le navigateur et expire avec lui, considérez les appels ci-dessous comme la description de ce que fait le tableau de bord, et non comme une intégration à automatiser. Pour un accès programmatique depuis votre propre backend, utilisez la Data API en lecture seule.
curl -X POST https://app.tracio.ai/api/v1/workspaces/{wsId}/webhooks \ -H "Authorization: Bearer <session-jwt>" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'Le secret de signature est généré par TRACIO et renvoyé une seule fois à la
création (et à la rotation) sous signingSecret. Conservez-le de manière sécurisée —
c'est la clé qui vous sert à vérifier les signatures.
{ "ok": true, "data": { "id": "b3d4f8a1-2c67-4e9b-8f05-7a1d3c9e2b48", "workspaceEnvironmentId": "b201f2ba-…", "url": "https://your-server.com/webhook/tracio", "events": [], "signingSecret": "f3a9…<hex>", "status": "active", "successRate": 100, "createdAt": "2026-07-30T12:00:00Z" }}Lors des lectures suivantes, le signingSecret est masqué (null) — il n'est révélé
que par la création et la rotation du secret.
| Méthode | Chemin | Description |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Lister les webhooks |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | Mettre à jour url / events / status |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Supprimer un webhook |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Envoyer une livraison de test signée |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Faire tourner le secret de signature |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | Lister les tentatives de livraison récentes |
Renvoyez un 2xx le plus vite possible et traitez le payload de façon asynchrone pour
éviter les timeouts :
app.post("/webhook/tracio", async (req, res) => { res.status(200).send("OK") processWebhookEvent(req.body).catch(console.error)})
async function processWebhookEvent(event: WebhookPayload) { await db.events.insert(event)
if (event.decision?.risk_score > 50) { await alertFraudTeam(event) }
if (event.bot?.result === "bot") { await blockVisitor(event.visitor_id) }}Utilisez l'action Test sur un webhook (ou POST .../webhooks/{webhookId}/test)
pour envoyer un payload d'exemple signé à votre endpoint et confirmer qu'il est
joignable et qu'il vérifie correctement les signatures.
Pour le développement local, exposez votre serveur avec un tunnel tel que ngrok :
ngrok http 3000# Use the generated URL as your webhook endpoint