I webhook recapitano al suo server gli eventi di identificazione in tempo reale. Ogni
volta che un visitatore viene identificato, TRACIO invia una richiesta HTTP POST
all'URL di webhook che ha configurato. Il corpo della richiesta è il payload
dell'evento.
Sono inoltre l'unico canale che recapita i verdetti tardivi — quelli in cui il comportamento di un visitatore ha dimostrato che era automatizzato dopo che la pagina si era già caricata.
Li configuri nella dashboard, sotto Settings → Webhooks. I webhook richiedono il piano Pro o superiore.
| Evento | Quando | Piano |
|---|---|---|
identification | A ogni visita — le fasi primary, late e correction | Tutti |
account_takeover | Il comportamento su un account non corrisponde più al profilo del suo titolare | Business+ |
account_assessment | Lo stato della valutazione del furto di account per un account: giudicato e regolare, giudicato e divergente, oppure non giudicato | Business+ |
attack_detected | Un picco di bot sul suo sito | Business+ |
reputation_changed | La reputazione di una persona collegata è passata a un'altra fascia | Business+ |
transaction_state_changed | L'esito di una transazione che ha inviato a POST /v2/transactions è cambiato | Business+ |
login_risk | Una valutazione del login tramite POST /v2/logins/assess si è conclusa con challenge o review | Tutti |
trusted_device_enrolled | Un dispositivo è stato reso attendibile per un account, oppure la sua attendibilità è stata rinnovata | Tutti |
trusted_device_revoked | L'attendibilità di un dispositivo è stata revocata — tramite l'API o dalla dashboard | Tutti |
affiliate_threshold_crossed | La raccomandazione per un affiliato è peggiorata (none → review, none → hold, review → hold) | Tutti |
I nomi degli eventi usano underscore, mai punti — non esistono visitor.created o
session.created.
Un webhook si iscrive a tipi specifici; il valore separato * significa «ogni tipo,
compresi quelli aggiunti in seguito». Cinque tipi fanno eccezione: * non include
account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked e affiliate_threshold_crossed — li indichi uno per uno
esplicitamente. account_assessment riporta la copertura anziché un riscontro,
quindi arriva più o meno una volta per visita che porta un linked_id — un ordine di
volume diverso da quello degli altri eventi. I tipi di rischio del login e di
affiliazione hanno senso solo per un'integrazione che chiama quelle API. Un carattere
jolly impostato prima che questi eventi esistessero non equivale al consenso a
riceverli.
Un tipo sconosciuto viene rifiutato con 400 alla creazione o alla modifica di
un'iscrizione, così un refuso non può lasciarle un webhook che in silenzio non scatta
mai.
identificationUna singola visita produce fino a tre recapiti che condividono lo stesso
request_id:
primary — il verdetto iniziale, al caricamento della pagina.late — arricchimento circa nove secondi dopo, una volta arrivati i controlli lenti.correction — una correzione basata sul comportamento (puntatore, tastiera, scorrimento).Li correli tramite request_id e li distingua tramite phase. La fase successiva
ha la precedenza: se primary diceva human e correction dice bot, la risposta
giusta è la seconda.
Non faccia affidamento sull'ordine di arrivo. Ogni fase viene recapitata in modo
indipendente e con il proprio calendario di retry: se primary è finito in retry
mentre late è riuscito al primo tentativo, li riceverà in ordine inverso. Determini
la precedenza dal campo phase, non dall'orario di ricezione.
Quelle tre sono le uniche fasi di un evento identification. Un altro valore le
arriva comunque: account_takeover e account_assessment portano phase: "beacon",
perché entrambi vengono sollevati dal beacon comportamentale della sessione.
Noti il disallineamento che ne nasce, perché tocca l'idempotenza. In produzione un
recapito identification ha un event_id esattamente pari a <request_id>:<phase>,
ma altri recapiti rompono quella formula. Un account_takeover è <request_id>:ato —
il suffisso è il letterale ato, non il valore del campo phase — e un
account_assessment è <request_id>:ato-state-<state>. Un recapito di prova inviato
dalla dashboard è <request_id>:test, mentre il phase nel suo corpo riporta ancora
primary — e un corpo schema 1 non ha affatto il campo phase, quindi l'unico posto
in cui quel suffisso compare è l'header. Usi event_id direttamente come chiave di
idempotenza e non lo ricomponga mai da request_id e phase. Faccia corrispondere i
valori che gestisce e ignori tutto il resto, invece di rifiutare il recapito.
Alcuni eventi non hanno una visita: attack_detected (livello workspace),
reputation_changed (livello persona), transaction_state_changed (livello
transazione), login_risk, trusted_device_enrolled e trusted_device_revoked
(livello account) e affiliate_threshold_crossed (livello affiliato). Non hanno
request_id, né visitor_id, né alcuno dei blocchi browser, geo, bot o
decision — quelle chiavi semplicemente non ci sono, così come l'header
X-Tracio-Request-Id. account_takeover e account_assessment, invece, sono
prodotti da una visita specifica e portano il corpo di identificazione completo
previsto dal suo piano. Se elabora tutti gli eventi in un unico handler, controlli
event prima di toccare i campi di visita.
I nuovi webhook usano la versione 3 del payload. I webhook esistenti sulla versione 1 o 2 mantengono la versione che hanno selezionato; entrambi gli schemi precedenti sono congelati e verranno rimossi il 2027-04-12. Per migrare, selezioni la versione 3 sulla scheda del webhook nella dashboard.
| Versione | Stato |
|---|---|
1 | Congelata; rimossa il 2027-04-12 |
2 | Congelata; rimossa il 2027-04-12 |
3 | L'impostazione predefinita per i nuovi webhook; chiavi snake_case |
La versione 3 porta gli stessi campi e valori della versione 2, con chiavi snake_case
e un version: 3 di primo livello. L'algoritmo di firma e gli header sono invariati
(X-Tracio-Payload-Version: 3). Le chiavi dentro il suo dizionario fields sono dati
suoi e non vengono rinominate.
| 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", // modello della scheda video, normalizzato; assente quando è sconosciuto "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 // il traffico HTTP e il percorso di rete grezzo escono da reti diverse }, "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}I valori zero e vuoti vengono omessi. I campi stringa e numerici con valore zero
(bot.type per un umano, oppure bot.antidetect_score: 0, per esempio) sono assenti
dal JSON: non li renda obbligatori nei suoi schemi e legga i blocchi annidati in modo
difensivo.
bot.score e decision.risk_score sono decimali su scala 0..100 con una cifra
dopo la virgola, esattamente i numeri che la dashboard e la Data API riportano per la
stessa visita. (Nello schema congelato v1 usano unità diverse: rispettivamente una
frazione 0..1 e 0..255.)
bot.type è il nome di un bot riconosciuto, un agente IA verificato
(ai_agent:<vendor>) oppure un'etichetta di famiglia. Veda
Tipi di bot per il vocabolario: i nomi interni dei
controlli non vengono mai esposti, su nessun piano. ai_agent:<vendor> significa che
la richiesta ha dimostrato di provenire dall'infrastruttura di quel fornitore — una
firma Web Bot Auth valida, fatta con una chiave che il fornitore pubblica, oppure un
indirizzo dentro gli intervalli IP che il fornitore pubblica — e non che si limita a
dichiararlo nello user agent. Una richiesta che dichiara di essere un agente IA ed è
smentita da tutte le prove che il fornitore pubblica viene riportata come
impersonation.
| Campo | Tipo | Descrizione |
|---|---|---|
version | number | Versione dello schema del payload (3) |
event | string | Tipo di evento |
event_id | string | Identificatore del recapito — la chiave di idempotenza; univoco per evento e condiviso da tutti i suoi webhook che lo ricevono, stabile fra i retry |
request_id | string | Identificatore della visita (UUID), condiviso da tutte le sue fasi |
phase | string | primary, late, correction; account_takeover e account_assessment portano beacon |
visitor_id | string | Identificatore di visitatore stabile |
linked_id | string | Identificatore collegato fornito dal client |
tag | string | Tag personalizzato fornito dal client |
fields | object | Campi personalizzati associati alla visita al momento della raccolta. Solo ciò che è arrivato con la visita — un campo associato in seguito tramite la Data API non compare mai in un webhook, in nessuna fase né retry. Chiavi e valori sono stringhe. Assente quando la visita non portava campi |
timestamp | string | Orario dell'evento (RFC 3339) |
url | string | URL della pagina in cui l'evento è stato catturato |
ip | string | Indirizzo IP del client |
user_agent | string | Stringa user-agent grezza del client |
browser.name / .version | string | Browser rilevato |
os.name / .version | string | Sistema operativo rilevato |
device | string | Classe di dispositivo (ad es. desktop, mobile) |
gpu | string | Modello della scheda video così come lo riporta il browser (WebGL), normalizzato in un nome leggibile (Intel Iris Xe Graphics, Apple M1 Pro); Software renderer per i rasterizzatori software; assente quando è sconosciuto |
geo | object | Geolocalizzazione da IP: country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (booleani) e connection_type |
network.proxy_detected | boolean | Il traffico HTTP della visita e i suoi percorsi di rete grezzi escono da reti diverse — un proxy o una VPN davanti al browser. Due indirizzi dello stesso operatore (NAT dell'operatore, una seconda uscita della stessa VPN) non contano |
bot.result | string | human, bot o uncertain |
bot.type | string | Nome del bot, agente IA verificato o etichetta di famiglia quando viene rilevato un bot |
bot.score | number | Punteggio di bot (0–100) |
identification.confidence | number | Confidenza dell'identificazione (0.0–1.0) |
identification.incognito | boolean | Contesto di navigazione privata/in incognito |
decision.action | string | real, fake o suspicious |
decision.risk_score | number | Punteggio di rischio aggregato (0–100) |
extensions | array | Estensioni del browser rilevate in questa visita, come slug macchina stabili (nomi, categorie e link agli store sono nella dashboard e nella Data API). Assente quando non è stato rilevato nulla |
Da Pro in su — come si comporta il visitatore nel tempo:
{ "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}Da Business in su — perché il verdetto è quello che è:
{ "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'indirizzo pubblico osservato sul percorso di rete grezzo, ossia // l'indirizzo dietro il proxy o la VPN; assente quando non è stato // osservato alcun indirizzo del genere "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // L'ambiente desktop MISURATO su una macchina Linux ("Mint 22+", "Ubuntu", // "GNOME", "KDE"); uno User-Agent non può esprimere una distribuzione. // Assente quando non è determinato — nella maggior parte delle visite // Linux e in tutte quelle non Linux. "os_environment": "Mint 22+", // Ciò che la visita ha dichiarato di sé rispetto a ciò che hanno misurato // controlli indipendenti. Presente solo quando una contraffazione è stata // effettivamente rilevata; un campo `real` vuoto significa "il controllo è // rimasto in silenzio", mai "confermato". Con l'asse `gpu`, `claimed.gpu` // porta la scheda dichiarata con lo stesso nome di modello leggibile del // campo `gpu` di primo livello. "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"] } }, // Dati del dispositivo — ciò che il browser del visitatore riporta sulla // macchina, ripulito dalla nostra parte. screen: risoluzione, profondità // di colore e device pixel ratio. locale: le lingue preferite e il fuso // orario del browser stesso — a differenza di geo.timezone, che è derivato // dall'indirizzo IP; una discordanza fra i due è un segno frequente di // posizione falsificata. client_hints: User-Agent Client Hints — // architettura e bitness della CPU, modello del dispositivo (Android: il // codice modello in `model`, ad es. "SM-A556B", e il suo nome commerciale // dall'elenco dei dispositivi Google Play in `device_name`, ad es. // "Samsung Galaxy A55 5G") e la versione esatta della piattaforma; li // riportano solo i browser basati su Chromium. Ogni blocco è assente // quando la visita non portava tali dati, quindi consideri ciascuno // facoltativo. "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" }, // Presente solo quando la scheda video si è dichiarata virtuale; // hypervisor è un dizionario chiuso (vmware, virtualbox, parallels, qemu, // hyperv, bochs, intel-gvt, vgpu). Un blocco assente significa che non c'è // alcun indizio del genere. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}Veda Rilevamento dei bot per il
vocabolario dei codici motivo e per il significato di severity.
Campi multi-account (da Business in su). Una volta attivata la modalità person per
il suo workspace, il corpo porta anche person_id, un blocco reputation (score,
categories, overall_risk), linked_accounts_count e linked_visitors_count —
cioè se il visitatore è collegato ad altri visitatori e account. Il livello person al
momento funziona in modalità di osservazione, e finché non entra in produzione questi
campi sono assenti dal corpo. Non li renda obbligatori nei suoi schemi.
guidance porta raccomandazioni pronte su «che cosa fare» per ciascun punto di
integrazione, così non deve ricavare una policy dai punteggi grezzi. È presente in
ogni evento v3 Business+ — allow viene indicato esplicitamente:
{ "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 }}Ogni scenario parte da allow e può solo salire lungo la scala:
allow → challenge → review → deny. All'interno di uno scenario vince l'asse
più severo che scatta, e overall è il più severo fra i quattro scenari.
| Indicazione | Pagamento | Registrazione | Login | Affiliazione |
|---|---|---|---|---|
allow | Lo elabori | Lo crei | Lo faccia entrare | Accrediti la conversione |
challenge | 3-D Secure / conferma | Captcha, conferma via e-mail o telefono | 2FA rafforzata, riautenticazione | La segni come dubbia finché non c'è attività |
review | Lo elabori, ma lo metta in coda di revisione | Lo crei con restrizioni | Lo faccia entrare e alzi un alert | Trattenga il pagamento fino alla revisione |
deny | Non elabori la transazione | Rifiuti la creazione dell'account | Non lo faccia entrare | Non accrediti la conversione |
basis elenca gli assi che hanno determinato l'indicazione — un asse la cui
proposta era più mite di quella adottata non entra nell'elenco. Lo legga per codice
invece di presumere un insieme fisso:
Asse (basis) | Che cosa significa |
|---|---|
list | Il visitatore corrispondeva a una delle liste del suo workspace in modalità enforce. Una lista allow prevale su ogni asse: ogni scenario diventa allow e basis è esattamente ["list"] |
rule | La visita corrispondeva a una delle regole del suo workspace in modalità enforce; una regola sposta solo l'indicazione del proprio scenario (una regola allow ammorbidisce solo quello) e viene saltata quando una lista ha già agito |
bot | Il rilevatore di bot ha concluso che si tratta di automazione — nega ogni scenario |
risk | La decisione e il punteggio di rischio complessivo della visita |
behavior | La biometria comportamentale indica un bot con sufficiente confidenza — aggiunge attrito anziché un rifiuto |
account_takeover | Il comportamento su questo account non corrisponde più al profilo del suo titolare — login in challenge, pagamento in review |
network | Tor, oppure una VPN che esce da un datacenter |
affiliate_pattern | La forma dei referral autogenerati — la conversione di affiliazione viene trattenuta come challenge |
fraud_reputation, multiaccounting | La reputazione e il raggruppamento degli account della persona dietro il visitatore; compaiono quando il livello person entra in produzione |
version è la versione dell'insieme di regole: viene incrementata man mano che la
logica migliora, quindi la conservi nei suoi log. La versione 2 ha introdotto l'asse
list, il primo che può ammorbidire un'indicazione; la versione 3 ha spostato le
soglie di login di account_takeover sulla scala del punteggio del verdetto di furto
di account, quindi la stessa visita può ricevere deny dove la versione 2 dava
challenge, e viceversa.
Guidance è additivo: nuovi scenari arrivano come nuove chiavi senza rompere il
contratto. Vince la fase successiva, tranne che per le indicazioni parziali: un
recapito calcolato su un insieme di input incompleto è contrassegnato con
"partial": true, e un'indicazione parziale non sovrascrive un'indicazione
completa ricevuta prima per lo stesso request_id. In un recapito ordinario il campo
partial è del tutto assente.
Le soglie esatte non sono documentate deliberatamente. Un'indicazione che può essere
sottoposta a reverse engineering fino a un punteggio smette di essere una difesa. C'è
esattamente un'eccezione deliberata: account_assessment.verdict.threshold, il
confine di decisione del verdetto di furto di account descritto più avanti.
account_takeoverSolo Business ed Enterprise; sui piani inferiori non viene creato alcun recapito,
anche se un webhook è iscritto a questo evento. Il corpo è l'envelope di
identificazione completo previsto dal suo piano più un blocco account_alert e il
blocco account_assessment descritto nella sezione successiva, recapitato al massimo
una volta per visita:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // l'allarme nasce da un beacon; solo l'event_id dice "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}Perché type porta una versione. La costruzione dietro il punteggio è già
cambiata in passato: la scala e la base del verdetto. behavior-drift/2 è la prima
costruzione con versione. Se ha calibrato le sue regole su quel numero, consideri un
cambio di questo valore come un segnale per ricontrollarle.
account_alert.drift_score e identification.drift_score sono lo stesso
numero (dal 2026-10-03): il punteggio comportamentale smussato su cui è stato
emesso il verdetto, misurato rispetto all'anello di finestre attendibili passate del
titolare dell'account. Prima di quella data identification.drift_score portava una
distanza grezza su una scala diversa — non mescoli valori a cavallo della data.
Quando una finestra non è stata giudicata, il campo è assente anziché zero. Usi
account_assessment.verdict quando le serve il numero insieme alla soglia con cui è
stato confrontato.
Nella v1 il blocco è accountAlert con type, linkedId e drift, e non c'è un
blocco di valutazione. Nella v2 l'allarme rinomina due campi — linkedId →
accountId e drift → driftScore — e aggiunge accountAssessment; la v3 usa i
nomi snake_case visti sopra. Aggiorni il suo handler quando cambia versione,
altrimenti la sua logica di furto di account smetterà silenziosamente di vedere i
dati.
account_assessmentSolo Business ed Enterprise. Richiede un'iscrizione esplicita: * non lo
include.
Senza questo evento, l'assenza di un allarme significa due cose diverse allo stesso tempo: o abbiamo valutato la sessione rispetto al profilo del titolare dell'account e corrispondeva, oppure non abbiamo potuto valutarla affatto — il profilo del titolare non è pronto, la finestra era troppo scarsa, oppure il traffico non era una persona. Entrambe le situazioni sembrano silenzio, e il silenzio si legge come sicurezza. Di solito non lo è: in una giornata di produzione completa di settembre 2026 ci siamo astenuti dal verdetto sul 73% delle finestre e sull'80% degli account. Un processo costruito su «nessun allarme significa che va bene» è costruito su uno stato che per lo più non abbiamo.
{ "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 non è mai assente e mai vuoto:
state | Significato | Che cosa fare |
|---|---|---|
assessed_clear | Giudicato; il comportamento corrisponde al titolare | Niente |
assessed_alert | Giudicato; il comportamento diverge | Step-up — l'allarme account_takeover porta lo stesso verdetto |
not_assessed | Nessun verdetto emesso | Non lo consideri pulito; ripieghi sui suoi segnali |
reason (solo con not_assessed):
reason | Significato |
|---|---|
profile_not_ready | Il riferimento del titolare al momento non può produrre un verdetto per questo account. Lo consideri uno stato, non una fase: potrebbe non cambiare mai, quindi non aspetti |
profile_learning | Il riferimento è ancora in fase di accumulo |
window_too_sparse | Una persona c'era, ma la finestra conteneva troppa poca interazione |
not_computable | La finestra e il riferimento non avevano assi informativi in comune |
bot_traffic | C'erano dati sufficienti, e non c'era alcuna persona da giudicare |
Dal 2026-10-04 18:00 UTC, window_too_sparse e not_computable non vengono più
emessi per un titolare il cui riferimento è pronto — una finestra del genere viene
riportata come profile_not_ready. I due motivi restano nell'elenco perché i recapiti
precedenti li portano: se il suo handler si dirama su di essi, instradi
profile_not_ready allo stesso modo, e non confronti i tassi di questi motivi a
cavallo di quella data.
state e reason non dipendono dal piano. verdict è Business+, come
drift_score.
Il blocco verdict è presente solo con assessed_clear e assessed_alert. Con
not_assessed il blocco è assente anziché riempito di zeri: uno score pari a 0
accanto a una threshold pari a 0 si leggerebbe come «il comportamento corrispondeva
esattamente».
| Campo | Significato |
|---|---|
severity | low o high — due fasce, deliberatamente: una fascia intermedia richiederebbe una seconda soglia sulla stessa scala |
score | Il valore su cui è stato emesso il verdetto |
threshold | Il valore con cui è stato effettivamente confrontato |
scale | Come è costruito il punteggio: manhattan-normalized è d/(1+d) in uno spazio comportamentale normalizzato, dove 0 significa corrispondenza esatta |
basis | ring — distanza dalla più vicina delle finestre attendibili passate del titolare; centroid — distanza dal suo profilo medio |
windows | Quante finestre sono state aggregate nel punteggio |
score e threshold sono sempre sulla stessa scala, dotata di un nome, quindi la
coppia riproduce la decisione: l'allarme scatta esattamente quando
score > threshold.
Con che frequenza arriva. Al massimo un recapito per stato per visita — in pratica
uno per visita che porta un linked_id, non uno per finestra comportamentale. Uno
stato può cambiare all'interno di una visita — per esempio, il riferimento finisce
l'apprendimento e not_assessed diventa assessed_clear — e allora li riceve
entrambi, in ordine. Quella transizione è possibile, non promessa: profile_not_ready
può persistere per l'intera vita dell'account.
Che cosa non promette. Gli account protetti meglio sono quelli di utenti attivi con sessioni lunghe e un profilo di riferimento completo; quelli protetti peggio sono gli utenti poco frequenti, per i quali un furto di account è più pericoloso. È una proprietà della costruzione, non una soglia che si possa regolare. L'evento riporta una divergenza comportamentale da un riferimento: non pretende di intercettare il furto di account in generale.
attack_detectedL'allarme per picco di bot arriva nell'envelope v3 comune con un blocco attack. Non
ha campi di identificazione: è un evento a livello di workspace:
{ "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 }}I webhook sulla versione 1 del payload ricevono lo schema storico piatto dell'allarme, che non cambia.
login_risk, trusted_device_enrolled e trusted_device_revokedQuesti tre eventi nascono dalle sue chiamate all'API di rischio del login
(POST /v2/logins/assess) e ai suoi dispositivi attendibili. Vengono recapitati solo
con un'iscrizione esplicita per nome — * non li include — e solo ai webhook
sulla versione 2 o 3 del payload; la versione 1 non ha un corpo per loro.
login_risk viene inviato quando una valutazione restituisce challenge o
review — mai su allow, deny o not_assessed. Il suo blocco login_risk è la
valutazione memorizzata, esattamente come l'ha data la risposta sincrona. Event id:
login-risk:<id>, dove <id> è il nostro identificatore del record memorizzato —
prenda il suo assessment_id dal corpo.trusted_device_enrolled e trusted_device_revoked vengono inviati a ogni
registrazione, rinnovo e revoca di un dispositivo attendibile. Il loro blocco
trusted_device — user_id, device_ref, enrolled_at, expires_at,
revoked_at, revoked_by (api o dashboard) — è un'istantanea al momento
dell'evento; con trusted_device_enrolled, revoked_at e revoked_by sono null.
Event id: trusted-device:<n>.Vengono inviati in modo asincrono, fino a circa cinque secondi dopo la chiamata, e
non portano l'header X-Tracio-Request-Id: usi login_risk.request_id per trovare la
visita. Il webhook è una notifica per audit e alerting; la decisione stessa è la
risposta sincrona.
{ "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_crossedRecapitato solo con un'iscrizione esplicita per nome — * non lo include — e solo
ai webhook sulla versione 2 o 3 del payload. Ogni 15 minuti TRACIO ricalcola il
punteggio di qualità di ciascun affiliato con dati sufficienti e invia l'evento quando
la sua raccomandazione peggiora: none → review, none → hold o review → hold. Un
miglioramento non invia nulla e permette di segnalare di nuovo il peggioramento
successivo. L'evento appartiene al workspace: va ai webhook iscritti di ogni ambiente
e non porta l'header X-Tracio-Request-Id. Event id:
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 sono le quote dell'affiliato negli ultimi 90 giorni, le stesse che mostra il
report della dashboard: la quota di registrazioni che hanno raggiunto un primo
deposito (reg_to_ftd), la quota di giocatori ancora attivi 14 giorni dopo la
registrazione (active14_share), e le quote di conversioni con un dispositivo o una
persona duplicati, provenienti da un anello di frode, da cacciatori di bonus, da un
datacenter, una VPN o un bot, etichettate come chargeback o come frode di affiliazione,
e senza una visita trovata. TRACIO si limita a raccomandare: la trattenuta stessa e
qualsiasi decisione sul pagamento restano nella sua piattaforma di affiliazione. Sulla
versione 2 del payload lo stesso corpo ha chiavi camelCase: il blocco è
affiliateThreshold, con affiliateId, previousRecommendation, qualityScore e
così via.
transaction_state_changedDa Business in su. Inviato quando cambia l'esito di una transazione che ha inviato a
POST /v2/transactions: le regole hanno deciso REVIEW o DECLINE (un APPROVE non
invia nulla), un analista ha mandato la transazione in revisione dalla dashboard,
oppure un'etichetta è stata impostata, sostituita o rimossa. Lo usi per trattenere un
bonus mentre una richiesta è in revisione e per negarlo o rilasciarlo una volta
definito l'esito, senza polling. * include questo evento; viene recapitato solo ai
webhook sulla versione 2 o 3 del payload. Un webhook legato a un ambiente lo riceve
solo per quell'ambiente.
{ "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 }}| Chiave | Significato |
|---|---|
effective_state | L'esito su cui agire: lo stato dell'analista o dell'etichetta quando è impostato, altrimenti state |
recommendations | Che cosa fare con il bonus, derivato da effective_state |
label, label_source, label_at | L'etichetta corrente, dove è stata impostata (api o dashboard) e quando; tutti e tre sono null quando la transazione non ha un'etichetta |
previous_effective_state | effective_state prima di questa modifica; null per l'evento inviato sulla decisione automatica |
Il blocco mostra la transazione così com'è quando l'evento viene inviato: se due
modifiche si susseguono rapidamente, entrambi gli eventi portano lo stato più recente,
ciascuno con il proprio previous_effective_state e timestamp. L'ordine non è
garantito: ordini per timestamp e legga la transazione tramite l'API per
conoscerne lo stato attuale. Event id: txn-state:<id>:created per la decisione
automatica e txn-state:<id>:<n> per ogni modifica successiva. L'evento non dice chi
ha impostato un'etichetta, solo da dove è arrivata.
reputation_changedDa Business in su. Inviato quando la reputazione cross-cliente di una persona che la
sua organizzazione ha visto passa a un'altra fascia (clean → suspicious, per
esempio). Richiede il livello person, che al momento funziona in modalità di
osservazione — quindi l'evento scatta solo per i workspace in cui è attiva la
risoluzione dell'identità cross-device. È un evento a livello di persona: non ha
request_id né blocchi di visita.
{ "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 chiave del blocco è reputation_change, non reputation: quest'ultima è occupata
dalla reputazione nel contesto di una visita specifica, e le due sono cose diverse. Lo
schema 1 recapita la forma storica piatta — gli stessi campi al primo livello.
Ogni recapito include un header X-Tracio-Signature:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t è il timestamp Unix (in secondi) in cui la richiesta è stata firmata.v1 è l'HMAC-SHA256 codificato in esadecimale di "<t>.<rawRequestBody>", con il
suo secret di webhook come chiave.Il timestamp fa parte del contenuto firmato, il che offre protezione dai replay.
Due cose da fare bene, altrimenti la verifica fallisce in produzione:
v1=. Durante una rotazione
del secret l'header porta due firme, e un parser che ne conserva solo una
rifiuterà recapiti validi per l'intera finestra di rotazione.// 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")})I recapiti con schema 2 e 3 portano in aggiunta X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Entrambe le parti conoscono il secret HMAC, quindi
l'HMAC dimostra che il mittente conosce il secret, ma non che la richiesta sia
originata da TRACIO; la firma asimmetrica sì. Le chiavi pubbliche sono pubblicate su
https://api.tracio.ai/.well-known/webhook-keys, indicizzate per kid: legga il
campo public_key. L'alias legacy publicKey porta lo stesso valore e verrà rimosso
il 2027-04-12.
I recapiti di prova inviati dalla dashboard sono firmati solo con HMAC: la chiave
privata di piattaforma risiede sui nodi di recapito e deliberatamente non è
disponibile alla dashboard. Un verificatore che richieda tassativamente Ed25519 deve
lasciar passare i recapiti di prova (portano il suffisso :test su event_id),
altrimenti i test dalla dashboard falliscono mentre la produzione è in salute. La
stessa cautela vale per i controlli di formato: un recapito di prova porta
request_id nella forma test_<hex> e il letterale test_visitor come visitor_id,
quindi un handler che li convalida rispetto alle forme di produzione rifiuterà un
recapito per tutto il resto perfettamente valido.
Dopo una rotazione entrambi i secret restano validi per 24 ore e l'header porta entrambe le firme, così può aggiornare la configurazione senza perdere recapiti. L'azione Revoke now accorcia la finestra. Aggiorni il secret dalla sua parte entro 24 ore: quando la finestra si chiude, il vecchio secret smette di corrispondere, e se il suo endpoint risponde a una firma non valida con un 4xx, cinque risposte di seguito disattivano il webhook.
| Header | Descrizione |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — due v1= durante una finestra di rotazione |
X-Tracio-Signature-Ed25519 | Firma di piattaforma, t=<unix>,kid=<id>,v1=<base64> (solo v2 e v3) |
X-Tracio-Event-Id | Identificatore del recapito — la chiave di idempotenza |
X-Tracio-Request-Id | Identificatore della visita, corrisponde a request_id (solo v2 e v3). Inviato solo per gli eventi di visita — identification, account_takeover e account_assessment |
X-Tracio-Event-Type | Il tipo di evento (solo v2 e v3) |
X-Tracio-Delivery-Attempt | Numero del tentativo, a partire da 1 (solo v2 e v3) |
X-Tracio-Payload-Version | 3 o 2 (solo v2 e v3) |
X-Tracio-Webhook-Id | Identificatore del webhook che ha prodotto questo recapito |
I recapiti possono essere ritentati, e un retry porta lo stesso
X-Tracio-Event-Id. Deduplichi su di esso:
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")})Noti che event_id è univoco per evento, non per webhook: se più webhook del
workspace sono iscritti allo stesso evento, ciascuno riceve un recapito con lo stesso
identificatore. Per identification è costruito come <request_id>:<phase>, ed è per
questo che le tre fasi di una stessa visita si deduplicano in modo indipendente invece
di collassare in una sola. Gli eventi senza visita hanno forme proprie: veda ciascun
evento sopra.
Risponda con 2xx: è l'unico segnale che un recapito è stato accettato.
| Risposta | Che cosa succede |
|---|---|
2xx | Recapito completato |
429 Too Many Requests | Non conta come fallimento e non consuma un tentativo; un Retry-After più lungo viene rispettato |
408, 425, 5xx, connessione caduta | Ritentato con una pausa crescente |
410 Gone | L'endpoint è considerato rimosso — il webhook viene disattivato immediatamente |
Altri 4xx | Ritentato, ma cinque di fila disattivano il webhook — 400/401/404 non si curano ritentando |
Calendario dei retry: 5 s → 30 s → 2 min → 10 min → 30 min → 2 h → 6 h (8 tentativi). I primi retry stanno dentro un minuto, quindi un riavvio breve del suo servizio non le costa una notifica. Ogni pausa è randomizzata fra la metà e il valore pieno, così i retry non partono tutti insieme dopo un'interruzione.
La disattivazione automatica richiede sia una soglia (20 fallimenti consecutivi, o 5 errori di configurazione) sia almeno 15 minuti consecutivi di fallimenti: un riavvio breve non può uccidere l'integrazione neanche con molti recapiti in coda. Un intervallo superiore a 15 minuti azzera il conteggio. La dashboard mostra il motivo, con il codice di risposta e il testo dell'errore, e un pulsante Re-enable che riporta a zero i contatori.
| Piano | Webhook per workspace |
|---|---|
| Free | Non disponibile |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Gli endpoint devono essere https con IP pubblico — gli indirizzi privati e di
loopback vengono rifiutati, anche su un redirect — e non più profondi di due redirect.
Vengono seguiti solo i redirect 307 e 308. 301, 302 e 303 istruiscono il
client a passare a GET e a scartare il corpo, quindi un recapito non li segue e il
tentativo conta come fallito. Se il suo load balancer normalizza l'URL (aggiungendo
www o una barra finale), punti il webhook direttamente all'URL finale.
I webhook si gestiscono nella dashboard. La dashboard pilota un'API di gestione con
ambito workspace, servita sull'host dell'applicazione (ad esempio
https://app.tracio.ai/api/v1), e gli endpoint qui sotto sono proprio quelli che
chiama. Tutti gli endpoint dei webhook risiedono sotto /workspaces/{wsId}.
Non è una superficie server-to-server. L'API di gestione accetta solo il JWT della sua sessione della dashboard, verificato rispetto al suo ruolo nel workspace (RBAC); una secret key
tracio_sk_…qui viene rifiutata. Poiché quella sessione vive nel browser e scade con esso, consideri le chiamate qui sotto come una descrizione di ciò che fa la dashboard, non come un'integrazione da automatizzare. Per l'accesso programmatico dal suo backend usi la Data API in sola lettura.
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": [] }'Il secret di firma è generato da TRACIO e restituito una sola volta alla creazione
(e alla rotazione) sotto signingSecret. Lo conservi in modo sicuro: è la chiave con
cui verifica le firme.
{ "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" }}Nelle letture successive il signingSecret è mascherato (null): viene rivelato solo
dalla creazione e dalla rotazione del secret.
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Elencare i webhook |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | Aggiornare url / events / status |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Eliminare un webhook |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Inviare un recapito di prova firmato |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Ruotare il secret di firma |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | Elencare i tentativi di recapito recenti |
Restituisca un 2xx il prima possibile ed elabori il payload in modo asincrono per
evitare i timeout:
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) }}Usi l'azione Test su un webhook (o POST .../webhooks/{webhookId}/test) per
inviare al suo endpoint un payload di esempio firmato e verificare che sia
raggiungibile e che controlli correttamente le firme.
Per lo sviluppo locale, esponga il suo server con un tunnel come ngrok:
ngrok http 3000# Use the generated URL as your webhook endpoint