Heb ik webhooks nodig als ik de Data API al gebruik?

Nee, maar de meeste teams draaien allebei. De Data API antwoordt over het bezoek waar je naar kijkt; webhooks vertellen je over de bezoeken waar je niet naar kijkt — een botaanval om 3 uur 's nachts, een accountovername in een sessie die niemand bekijkt. Webhooks dragen bovendien latere fasen: een verdict dat door tragere aanwijzingen is gecorrigeerd komt binnen als nieuwe levering.

Wat gebeurt er als mijn endpoint uit ligt?

We proberen het opnieuw op een oplopende ladder — 5 s, 30 s, 2 min, 10 min, 30 min, 2 u, 6 u — acht pogingen verspreid over ruwweg 4,4 tot 8,7 uur, met elke pauze gerandomiseerd zodat herhaalpogingen niet als één salvo aankomen. Een herstart die een minuut duurt kost je niets, en een webhook wordt pas uitgeschakeld na een reeks fouten die zowel de drempel bereikt als minstens 15 aaneengesloten minuten aanhoudt.

Moet ik beide handtekeningen verifiëren?

De HMAC verifiëren is genoeg voor de meeste integraties en werkt op beide payloadschema's. De Ed25519-platformhandtekening is de sterkere optie — een publieke sleutel in plaats van een gedeeld secret — en komt mee met schema 2. Vereist jouw verificatie hem, laat testleveringen vanuit het dashboard dan toch door: die dragen per ontwerp alleen de HMAC, omdat de private platformsleutel de leverknopen nooit verlaat.

Kunnen de Data API en een webhook het oneens zijn over hetzelfde bezoek?

Ze kunnen verschillen, en dat is geen tegenspraak. De Data API antwoordt vanuit het primaire record — wat bekend was bij het laden van de pagina. Latere fasen bereiken je als webhookleveringen en worden daar niet in teruggeschreven. Ze beantwoorden verschillende vragen: wat we op dat moment wisten, tegenover wat we concludeerden terwijl er aanwijzingen bleven binnenkomen. Handel je minuten na het bezoek, vertrouw dan op de fase die je als laatste hebt ontvangen.

Welk abonnement heb ik nodig?

Webhooks beginnen bij Pro — vijf per workspace, 20 op Business, 100 op Enterprise. De Data API is vanaf Pro. Guidance, reason codes bij het verdict, gedragssignalen en browseroverstijgende apparaatdata zijn vanaf Business.

Datalevering

Jouw data, daar waar jij de beslissing neemt

Elke identificatie kan je systemen op twee manieren bereiken: gepusht naar je server op het moment dat het gebeurt, of door jou opgehaald op precies de seconde dat je beslist. Beide kanalen dragen dezelfde getallen — dat stuk ligt vast in een test, niet in een belofte.

Gratis proberen Demo boeken

Twee kanalen

Push of pull

Webhooks pushen events naar je toe zodra ze gebeuren. Met de Data API vraag je het op het moment dat je een antwoord nodig hebt. De meeste teams draaien allebei: webhooks om vast te leggen en te reageren, de Data API om inline te controleren.

Webhooks — push, realtime

We POSTen een ondertekend JSON-event naar jouw endpoint zodra er iets gebeurt: een bezoeker wordt geïdentificeerd, een accountovername wordt gemarkeerd, een botaanval begint. Niets te pollen, niets in te plannen.

Het best voor: elk bezoek vastleggen, op aanvallen reageren, je warehouse of SIEM voeden.

p50-leverlatentie 44–140 ms, van event tot jouw endpoint.

Data API — pull, op aanvraag

Een private server-naar-server-API. Je backend authenticeert met een geheime sleutel en leest precies wat wij over een bezoeker weten op de seconde dat hij beslist — meestal binnen een login- of checkouthandler.

Het best voor: een inline controle voordat je een kaart belast, een aanmelding goedkeurt of een account ontgrendelt.

Beschikbaar vanaf het Pro-abonnement.

Webhooks

Vier eventtypes, één envelop

Elke levering komt in dezelfde envelop, met het eventtype in de body en in de header X-Tracio-Event-Type — zo kan één handler alle vier routeren.

Bezoeker geïdentificeerd

Het kernevent: een bezoek is beoordeeld. Het draagt de visitor ID, browser en besturingssysteem, geo en netwerk, het botverdict en de risicobeslissing. Het wordt in fasen geleverd — een primair event bij het laden van de pagina, daarna een late fase of correctiefase wanneer tragere aanwijzingen het verdict veranderen. Fasen correleer je via requestId.

identification

Accountovername

De detector voor accountovername is afgegaan op een bezoek: het apparaat achter een bekend account lijkt niet meer op het apparaat dat het account bezit. Het komt als een eigen event binnen, met de accountcontext erbij, in plaats van weggestopt in een identificatiebody.

account_takeover

Botaanval

Een golf geautomatiseerd verkeer op je workspace. Achter dit event zit geen bezoek — het is een melding op workspaceniveau, dus de bezoekblokken ontbreken gewoon in de body in plaats van binnen te komen als lege hulzen met op nul gezette scores.

attack_detected

Reputatiewijziging

Een profiel is van reputatieband gewisseld. Dezelfde envelop als de aanvalsmelding — een event op profielniveau zonder gekoppeld bezoek, dat de nieuwe en de vorige band draagt.

reputation_changed

Een levering, ingekort

Dit is de basisbody. Pro voegt bezoeksnelheid toe; Business voegt reason codes bij het verdict, gedragssignalen, guidance en browseroverstijgende apparaatdata toe aan exact dezelfde vorm — er komen nieuwe blokken bij, bestaande paden verschuiven nooit.

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 }
}

Elk verzoek draagt twee handtekeningen

X-Tracio-Signature is een HMAC-SHA256 over de signature-timestamp samengevoegd met de ruwe request body, met jouw webhook secret als sleutel — die bewijst dat de afzender het secret kent dat jullie allebei hebben. X-Tracio-Signature-Ed25519 is de platformhandtekening: die verifieer je met een publieke sleutel die je van een well-known endpoint haalt, dus aan jouw kant hoeft niets geheims te worden opgeslagen. De timestamp maakt deel uit van de ondertekende inhoud, en juist dat maakt een oude opname waardeloos voor replay.

Verifieer tegen de ruwe request bytes — opnieuw geserialiseerde JSON verandert de bytes en dan komt de handtekening niet overeen. Herhaalpogingen dragen dezelfde X-Tracio-Event-Id, dus dedupliceer daarop.

Headers bij elke levering

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

Betrouwbaarheid

Gebouwd om geen events te verliezen

De levering draait op een eigen fleet, en de bron van waarheid is de queue — niet het geheugen van een proces. Juist dat maakt at-least-once echt: sterft een leverknoop halverwege, dan staat het event nog in de queue en pikt een andere knoop het op.

events per seconde door één webhook — vóór de herbouw van juli was dat ongeveer 50

44–140 msp50-leverlatentie van event tot jouw endpoint

leverpogingen op een oplopende ladder, verspreid over maximaal 8,7 uur

van de 90.000 events geleverd in een test waarbij een leverknoop onder belasting werd afgeschoten

Herhaalpogingen die bij echte storingen passen

5 s, 30 s, 2 min, 10 min, 30 min, 2 u, 6 u. De eerste herhaalpogingen landen binnen een minuut, dus een korte herstart van je dienst kost je niets. Elke pauze wordt willekeurig gekozen tussen de helft van de genoemde waarde en de volle waarde, zodat herhaalpogingen na een storing niet als één salvo terugkomen.

Automatisch uitschakelen dat niet misgaat

Een webhook wordt pas uitgeschakeld wanneer de fouten zowel de drempel bereiken als minstens 15 aaneengesloten minuten aanhouden — een golf opgespaarde leveringen tijdens een herstart nekt de integratie dus niet. Een 410 Gone schakelt meteen uit. Het dashboard toont de reden, de responscode en een knop om hem weer aan te zetten.

Secret roteren zonder gat

Na een rotatie blijven beide secrets 24 uur geldig en draagt de header beide handtekeningen, dus een match op één ervan is genoeg. Je werkt je configuratie binnen dat venster bij in plaats van tegen een omschakelmoment te racen; “Nu intrekken” kort het venster in wanneer het meteen weg moet.

Een leverlog dat te lezen valt

Elke poging — responscode, duur, foutmelding — is per webhook zichtbaar in het dashboard, naast een testactie die een ondertekende voorbeeldpayload naar jouw endpoint stuurt zodat je je verificatie kunt bevestigen voordat je live gaat.

Data API

Vraag het op het moment dat je beslist

Een private server-naar-server-API op api.tracio.ai. Je backend authenticeert met een geheime sleutel en leest zijn eigen data. Hij stuurt bewust geen CORS-headers: een geheime sleutel geeft toegang tot alles in je workspace en mag nooit in een browser terechtkomen. Beschikbaar vanaf het Pro-abonnement.

Methode	Pad	Levert
GET	/v1/visitors/{visitorId}	Bezoekerssamenvatting: voor het eerst en voor het laatst gezien, aantal bezoeken, unieke IP's en landen, browsers en apparaten, risicohistorie — plus de meest recente sessie.
GET	/v1/visitors/{visitorId}/sessions	Sessielijst met cursorpaginering en filters op periode, botresultaat en minimale risicoscore.
GET	/v1/visitors/{visitorId}/sessions/latest	De meest recente sessie als één object, zonder lijstenvelop.
GET	/v1/sessions/{requestId}	Eén specifieke sessie. Geef visitorId mee en de opzoeking loopt via de bezoekersindex in plaats van via je hele historie.
GET	/v1/visitors/{visitorId}/velocity	Activiteit over een venster — 1 u, 24 u of 7 d: hoeveel bezoeken, vanaf hoeveel IP's, uit hoeveel landen, onder hoeveel accounts.

Een bezoeker controleren bij het afrekenen

De typische call: binnen je betaalhandler, voordat je de kaart autoriseert. Eén verzoek, één antwoord, en het meta-blok meldt het venster dat je werkelijk hebt gekregen — vraag je zes maanden en bewaart jouw abonnement 30 dagen, dan komen er 30 dagen terug en staat dat er ook bij.

Verzoek

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"

Antwoord

JSON

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

Overal dezelfde getallen

Een bezoek dat in je dashboard 65,9 scoort, scoort 65,9 in de Data API en 65,9 in de webhookbody. Twee onafhankelijke weergaven zouden uit elkaar kunnen lopen — schalen zijn het klassieke geval, waarbij het ene kanaal je 0,93 geeft waar het andere 93 zegt — dus bouwt een pariteitstest één bezoek, rendert dat door beide kanalen en vergelijkt de publieke velden op ruwe JSON. De overeenkomst wordt afgedwongen, niet beweerd.

Guidance — vanaf Business

Advies, niet alleen getallen

Scores vertellen je wat we zagen. Guidance vertelt je wat je ermee moet, voor de vier beslissingen die daadwerkelijk geld kosten — berekend door geversioneerde regels, met de onderbouwing erbij.

Betaling aannemen?

Weegt risico, fraudereputatie en het botverdict voordat je een kaart autoriseert.

Aanmelding accepteren?

Vangt het wegwerpaccount af voordat het bestaat — multi-accounting en reputatie wegen hier het zwaarst.

Binnenlaten?

Trekt automatisch aan wanneer de detector voor accountovername op dit bezoek is afgegaan.

Conversie meetellen?

Scheidt een echte verwijzing van een zelfverwijzing of een beloonde bot.

Een woordenschat van vier woorden

allowNiets waarop je hoeft te handelen.

challengeVraag om een tweede factor.

reviewHoud het vast voor een mens.

denyRonduit weigeren.

Elk scenario krijgt een van vier antwoorden, en daarbij de basis waarop het is afgegeven — de doorslaggevende assen uit een vaste woordenschat: bot, risico, fraudereputatie, gedrag, multi-accounting, accountovername, netwerk, affiliatepatroon. Je weet altijd welke as het advies heeft bewogen, zonder ooit signaalnamen, gewichten of drempels te zien.

Eén berekening, drie kanalen

Hetzelfde guidance-blok reist mee in de webhook, antwoordt in de Data API en verschijnt op de bezoekerskaart in het dashboard — één regelset, één uitkomst, geen afstemming aan jouw kant. Lees het advies voor jouw scenario en niet overall: overall is simpelweg de strengste van de vier, een samenvatting voor dashboards en geen betaalbeslissing. De regelversie zit in de payload, dus een regelwijziging merk je, in plaats van dat je hem afleidt uit advies dat is verschoven.

JSON

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

Integratie

Vijf SDK's aan de voorkant, twee kanalen aan de achterkant

De browserkant komt als vijf SDK's — vanilla JavaScript, React, Vue 3, Angular en Svelte 5. Server-side SDK's zijn er niet, en dat is bewust: je backend integreert over gewone HTTP via ondertekende webhooks en de Data API. Handtekeningverificatie is een stuk of twaalf regels tegen een referentievector die wij publiceren, en er is niets extra's dat je in je serverafhankelijkheden bij moet houden.

Browser-SDK's

JavaScriptReactVue 3AngularSvelte 5

Bekijk de SDK's API-referentie Webhookdocumentatie

FAQ

Veelgestelde vragen

In één middag aangesloten

Maak een webhook aan in het dashboard, richt hem op jouw endpoint en druk op Test. Verifieer de handtekening tegen onze referentievector, en het moeilijke deel ligt achter je.

Gratis proberen Demo boeken