Mi servono i webhook se uso già la Data API?

No, ma la maggior parte dei team usa entrambi. La Data API risponde sulla visita che ha davanti; i webhook le parlano delle visite che non sta guardando — un attacco di bot alle 3 del mattino, un furto di account su una sessione che nessuno sta osservando. I webhook portano anche le fasi successive: un verdetto corretto da prove più lente arriva come nuova consegna.

Cosa succede se il mio endpoint è offline?

Ritentiamo su una scala crescente — 5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h — otto tentativi distribuiti su circa 4,4-8,7 ore, con ogni pausa randomizzata così i ritentativi non arrivano in un'unica salva. Un riavvio che dura un minuto non le costa nulla, e un webhook viene disattivato solo dopo una serie di fallimenti che raggiunge la soglia e dura almeno 15 minuti consecutivi.

Devo verificare entrambe le firme?

Verificare l'HMAC è sufficiente per la maggior parte delle integrazioni e funziona su entrambi gli schemi di payload. La firma di piattaforma Ed25519 è l'opzione più forte — una chiave pubblica invece di un segreto condiviso — e viaggia con lo schema 2. Se il suo verificatore la richiede, lasci passare le consegne di test della dashboard: sono solo HMAC per scelta, perché la chiave privata della piattaforma non lascia mai i nodi di consegna.

La Data API e un webhook possono essere in disaccordo sulla stessa visita?

Possono differire, e non è una contraddizione. La Data API risponde dal record primario — ciò che si sapeva al caricamento della pagina. Le fasi successive le arrivano come consegne webhook e non vengono riunite in quel record. Rispondono a domande diverse: cosa sapevamo in quel momento, contro cosa abbiamo concluso man mano che le prove continuavano ad arrivare. Se agisce minuti dopo la visita, si fidi dell'ultima fase ricevuta.

Di quale piano ho bisogno?

I webhook partono da Pro — cinque per workspace, 20 su Business, 100 su Enterprise. La Data API è da Pro in su. Guidance, codici motivazione del verdetto, segnali comportamentali e dati del dispositivo tra browser diversi sono da Business in su.

Consegna dei dati

I suoi dati, dove prende la decisione

Ogni identificazione può raggiungere i suoi sistemi in due modi: spinta al suo server nell'istante in cui avviene, oppure richiesta da lei nel secondo esatto in cui decide. Entrambi i canali portano gli stessi numeri — e questo è garantito da un test, non da una promessa.

Inizi la prova gratuita Prenoti una demo

Due canali

Push o pull

I webhook le spingono gli eventi mentre accadono. La Data API le permette di chiedere nel momento in cui le serve una risposta. La maggior parte dei team usa entrambi: i webhook per registrare e reagire, la Data API per il controllo in linea.

Webhook — push, in tempo reale

Inviamo in POST un evento JSON firmato al suo endpoint nell'istante in cui succede qualcosa: un visitatore viene identificato, viene segnalato un furto di account, inizia un attacco di bot. Niente polling, niente pianificazioni.

Ideale per: registrare ogni visita, reagire agli attacchi, alimentare il suo data warehouse o SIEM.

Latenza di consegna p50 44–140 ms, dall'evento al suo endpoint.

Data API — pull, su richiesta

Un'API privata da server a server. Il suo backend si autentica con una chiave segreta e legge esattamente ciò che sappiamo di un visitatore nel secondo in cui decide — tipicamente dentro un handler di login o di checkout.

Ideale per: un controllo in linea prima di addebitare una carta, approvare un'iscrizione o sbloccare un account.

Disponibile dal piano Pro.

Webhook

Quattro tipi di evento, una sola busta

Ogni consegna arriva nella stessa busta, con il tipo di evento nel corpo e nell'header X-Tracio-Event-Type — così un solo handler può instradare tutti e quattro.

Visitatore identificato

L'evento centrale: una visita è stata valutata. Porta l'ID visitatore, browser e sistema operativo, geolocalizzazione e rete, il verdetto sui bot e la decisione di rischio. Viene consegnato in fasi: un evento primario al caricamento della pagina, poi una fase tardiva o di correzione quando prove più lente cambiano il verdetto. Correli le fasi tramite requestId.

identification

Furto di account

Il rilevatore di furto di account è scattato su una visita: il dispositivo dietro un account noto non somiglia più al dispositivo che lo possiede. Arriva come evento proprio, con il contesto dell'account allegato, invece di nascondersi dentro un corpo di identificazione.

account_takeover

Attacco di bot

Un'ondata di traffico automatizzato sul suo workspace. Questo non ha una visita alle spalle: è un avviso a livello di workspace, quindi i blocchi relativi alla visita sono semplicemente assenti dal corpo invece di arrivare come gusci vuoti con punteggi azzerati.

attack_detected

Cambio di reputazione

Un profilo si è spostato tra fasce di reputazione. Stessa busta dell'avviso di attacco — un evento a livello di profilo senza visita allegata, che porta la nuova fascia e quella precedente.

reputation_changed

Una consegna, ridotta all'essenziale

Questo è il corpo base. Pro aggiunge la velocity delle visite; Business aggiunge i codici motivazione del verdetto, i segnali comportamentali, la guidance e i dati del dispositivo tra browser diversi alla stessa identica forma — compaiono blocchi nuovi, i percorsi esistenti non si spostano mai.

JSON

{
  "version": 2,
  "event": "identification",
  "eventId": "req_8f21c4:primary",
  "requestId": "req_8f21c4",
  "phase": "primary",
  "visitorId": "3f9a1b2c4d5e6f70",
  "timestamp": "2026-07-30T12:00:00Z",
  "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" },
  "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false },
  "bot": { "result": "human", "score": 12 },
  "identification": { "confidence": 0.97, "incognito": false },
  "decision": { "action": "suspicious", "riskScore": 65.9 }
}

Ogni richiesta porta due firme

X-Tracio-Signature è un HMAC-SHA256 sul timestamp della firma unito al corpo grezzo della richiesta, con la chiave del suo webhook segreto: dimostra che il mittente conosce il segreto che entrambi custodite. X-Tracio-Signature-Ed25519 è la firma della piattaforma: la verifica con una chiave pubblica recuperata da un endpoint noto, quindi dalla sua parte non c'è nulla di segreto da conservare. Il timestamp fa parte del contenuto firmato, ed è questo a rendere inutile riprodurre una cattura vecchia.

Verifichi sui byte grezzi della richiesta: un JSON riserializzato cambia i byte e la firma non corrisponderà. I tentativi ripetuti portano lo stesso X-Tracio-Event-Id, quindi usi quello per la deduplicazione.

Header presenti in ogni consegna

Text

X-Tracio-Signature:         t=1753444800,v1=5257a869e7ecebed...
X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...
X-Tracio-Event-Type:        identification
X-Tracio-Event-Id:          req_8f21c4:primary
X-Tracio-Delivery-Attempt:  1
X-Tracio-Payload-Version:   2

Affidabilità

Costruito per non perdere eventi

La consegna gira su una flotta dedicata, e la fonte di verità è la coda, non la memoria di un processo. È questo a rendere reale la garanzia at-least-once: se un nodo di consegna muore a metà volo, l'evento è ancora in coda e un altro nodo lo raccoglie.

eventi al secondo attraverso un singolo webhook, contro circa 50 prima della riscrittura di luglio

44–140 mslatenza di consegna p50 dall'evento al suo endpoint

tentativi di consegna su una scala crescente, distribuiti su un massimo di 8,7 ore

dei 90.000 eventi consegnati in un'esercitazione che ha ucciso un nodo di consegna sotto carico

Ritentativi tarati sui guasti reali

5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. I primi ritentativi arrivano entro un minuto, così un breve riavvio del suo servizio non le costa nulla. Ogni pausa viene scelta a caso tra metà del valore indicato e il valore pieno, così i ritentativi non tornano come un'unica salva dopo un guasto.

Disattivazione automatica che non parte a sproposito

Un webhook viene spento solo quando i fallimenti raggiungono la soglia e durano da almeno 15 minuti consecutivi — una raffica di consegne accodate durante un riavvio non uccide l'integrazione. Un 410 Gone disattiva immediatamente. La dashboard mostra il motivo, il codice di risposta e un pulsante per riattivare.

Rotazione del segreto senza interruzioni

Dopo una rotazione entrambi i segreti restano validi per 24 ore e l'header porta entrambe le firme, quindi basta che una delle due corrisponda. Aggiorna la configurazione dentro la finestra invece di rincorrere un passaggio secco; «Revoca adesso» accorcia la finestra quando le serve chiuderla subito.

Un registro delle consegne leggibile

Ogni tentativo — codice di risposta, durata, testo dell'errore — è visibile per webhook nella dashboard, accanto a un'azione di test che invia al suo endpoint un payload di esempio firmato, così può verificare il suo verificatore prima di andare in produzione.

Data API

Chieda nel momento in cui decide

Un'API privata da server a server su api.tracio.ai. Il suo backend si autentica con una chiave segreta e legge i propri dati. Deliberatamente non invia header CORS: una chiave segreta dà accesso a tutto il suo workspace e non deve mai raggiungere un browser. Disponibile dal piano Pro.

Metodo	Percorso	Restituisce
GET	/v1/visitors/{visitorId}	Riepilogo del visitatore: prima e ultima visita, numero di visite, IP e paesi unici, browser e dispositivi, storico di rischio — più la sua sessione più recente.
GET	/v1/visitors/{visitorId}/sessions	Elenco delle sessioni con paginazione a cursore e filtri per intervallo di date, esito bot e punteggio di rischio minimo.
GET	/v1/visitors/{visitorId}/sessions/latest	La sessione più recente come singolo oggetto, senza busta di lista.
GET	/v1/sessions/{requestId}	Una sessione specifica. Passi anche visitorId e la ricerca passa dall'indice dei visitatori invece che dall'intero storico.
GET	/v1/visitors/{visitorId}/velocity	Attività su una finestra — 1h, 24h o 7d: quante visite, da quanti IP, da quanti paesi, sotto quanti account.

Controllare un visitatore al checkout

La chiamata tipica: dentro il suo handler di pagamento, prima di autorizzare la carta. Una richiesta, una risposta, e il blocco meta riporta la finestra che ha davvero ottenuto — se chiede sei mesi e il suo piano ne conserva 30 giorni, restituisce 30 giorni e lo dichiara.

Richiesta

bash

# Inside your checkout handler, before you authorize the card
curl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
  "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"

Risposta

JSON

{
  "window": "24h",
  "events": 128,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "uniqueAccounts": 1,
  "meta": { "plan": "business", "retentionDays": 30 }
}

Gli stessi numeri ovunque

Una visita che nella sua dashboard vale 65,9 vale 65,9 nella Data API e 65,9 nel corpo del webhook. Due rappresentazioni indipendenti potrebbero divergere — le scale sono il caso classico, un canale che le porge 0,93 dove l'altro dice 93 — perciò un test di parità costruisce una singola visita, la rende attraverso entrambi i canali e confronta i campi pubblici sul JSON grezzo. La coincidenza è imposta, non dichiarata.

Guidance — da Business in su

Consigli, non solo numeri

I punteggi le dicono cosa abbiamo visto. La guidance le dice cosa farne, per le quattro decisioni che costano davvero denaro — calcolata da regole versionate, con il ragionamento allegato.

Accettare il pagamento?

Pesa rischio, reputazione di frode e verdetto sui bot prima che autorizzi una carta.

Accettare l'iscrizione?

Intercetta l'account usa e getta prima che esista — qui multi-account e reputazione pesano di più.

Farlo entrare?

Si irrigidisce automaticamente quando il rilevatore di furto di account è scattato sulla visita.

Contare la conversione?

Distingue un referral genuino da un auto-referral o da un bot incentivato.

Un vocabolario di quattro parole

allowNiente su cui valga la pena agire.

challengeChieda un secondo fattore.

reviewLo trattenga per una persona.

denyRifiuti senza appello.

Ogni scenario riceve una di quattro risposte, e con essa la base su cui è stata emessa — gli assi decisivi da un vocabolario fisso: bot, rischio, reputazione di frode, comportamento, multi-account, furto di account, rete, schema di affiliazione. Sa sempre quale asse ha mosso il consiglio, senza vedere mai nomi di segnali, pesi o soglie.

Un solo calcolo, tre canali

Lo stesso blocco di guidance viaggia nel webhook, risponde nella Data API e viene mostrato sulla scheda del visitatore nella dashboard — un solo insieme di regole, un solo risultato, nessuna riconciliazione dalla sua parte. Legga il consiglio relativo al suo scenario invece di quello complessivo: il complessivo è semplicemente il più severo dei quattro, un riassunto per le dashboard e non una decisione di pagamento. La versione delle regole viaggia nel payload, così un cambio di regole è qualcosa che nota, non qualcosa che deduce da un consiglio che si è spostato.

JSON

"guidance": {
  "version": 1,
  "overall": "review",
  "payment": "review",
  "registration": "challenge",
  "login": "allow",
  "affiliate": "allow",
  "basis": ["risk", "fraud_reputation"]
}

Integrazione

Cinque SDK sul front end, due canali sul back

Il lato browser viene distribuito come cinque SDK: JavaScript puro, React, Vue 3, Angular e Svelte 5. Non esistono SDK lato server, ed è una scelta deliberata: il suo backend si integra su semplice HTTP tramite webhook firmati e la Data API. La verifica della firma sta in una dozzina di righe rispetto a un vettore di riferimento che pubblichiamo, e non c'è nulla in più da continuare ad aggiornare nell'albero delle dipendenze del suo server.

SDK per browser

JavaScriptReactVue 3AngularSvelte 5

Sfoglia gli SDK Riferimento API Documentazione dei webhook

FAQ

Domande frequenti

Lo colleghi in un pomeriggio

Crei un webhook nella dashboard, lo punti al suo endpoint e prema Test. Verifichi la firma rispetto al nostro vettore di riferimento, e la parte difficile è alle spalle.

Inizi la prova gratuita Prenoti una demo