Vaše data tam, kde se rozhodujete
Každá identifikace se k vašim systémům dostane dvěma cestami: přijde na váš server ve chvíli, kdy nastane, nebo si ji vyžádáte přesně ve vteřině, kdy se rozhodujete. Oba kanály nesou stejná čísla — to hlídá test, ne slib.
Push, nebo pull
Webhooky vám posílají události, jak přicházejí. Data API vám dovolí se zeptat ve chvíli, kdy potřebujete odpověď. Většina týmů provozuje obojí: webhooky k zaznamenávání a reakci, Data API ke kontrole v průběhu.
Webhooky — push, v reálném čase
Pošleme POST s podepsanou JSON událostí na váš endpoint ve chvíli, kdy se něco stane: návštěvník je identifikován, je označeno převzetí účtu, začíná útok botů. Nic se nedotazuje, nic se neplánuje.
Nejlepší na: zaznamenání každé návštěvy, reakci na útoky, plnění datového skladu nebo SIEM.
Doručovací latence p50 44–140 ms, od události k vašemu endpointu.
Data API — pull, na vyžádání
Privátní API mezi servery. Váš backend se ověří tajným klíčem a přečte si přesně to, co o návštěvníkovi víme, ve vteřině, kdy se rozhoduje — typicky uvnitř obsluhy přihlášení nebo objednávky.
Nejlepší na: průběžnou kontrolu, než strhnete platbu z karty, schválíte registraci nebo odemknete účet.
Dostupné od plánu Pro.
Čtyři typy událostí, jedna obálka
Každé doručení přijde v téže obálce, s typem události v těle i v hlavičce X-Tracio-Event-Type — takže všechny čtyři může směrovat jediná obsluha.
Návštěvník identifikován
Hlavní událost: návštěva byla vyhodnocena. Nese ID návštěvníka, prohlížeč a OS, geolokaci a síť, verdikt o botech a rozhodnutí o riziku. Doručuje se ve fázích — primární událost při načtení stránky, pak pozdní nebo opravná fáze, když pomalejší důkazy změní verdikt. Fáze spojíte přes requestId.
identificationPřevzetí účtu
Na návštěvě se spustil detektor převzetí účtu: zařízení za známým účtem už nevypadá jako zařízení, kterému účet patří. Přichází jako vlastní událost s připojeným kontextem účtu, místo aby se schovávalo uvnitř těla identifikace.
account_takeoverÚtok botů
Nárůst automatizovaného provozu ve vašem pracovním prostoru. Za touhle událostí není žádná návštěva — je to upozornění na úrovni pracovního prostoru, takže bloky návštěvy v těle prostě chybí, místo aby přišly jako prázdné skořápky s vynulovanými skóre.
attack_detectedZměna reputace
Profil se posunul mezi reputačními pásmy. Táž obálka jako u upozornění na útok — událost na úrovni profilu bez připojené návštěvy, nesoucí nové pásmo i to předchozí.
reputation_changedDoručení, zkráceně
Tohle je základní tělo. Pro přidává rychlost návštěv; Business přidává do naprosto stejného tvaru kódy důvodů verdiktu, signály chování, guidance a data o zařízení napříč prohlížeči — nové bloky přibudou, stávající cesty se nikdy neposunou.
{ "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 }}Každý požadavek nese dva podpisy
X-Tracio-Signature je HMAC-SHA256 nad časovým razítkem podpisu spojeným se surovým tělem požadavku, klíčovaný vaším webhookovým tajemstvím — dokazuje, že odesílatel zná tajemství, které máte oba. X-Tracio-Signature-Ed25519 je podpis platformy: ověříte ho veřejným klíčem staženým z well-known endpointu, takže si u sebe nemusíte nic tajného držet. Časové razítko je součástí podepsaného obsahu, a právě to činí starý odchycený požadavek nepoužitelným k opakovanému odeslání.
Ověřujte proti surovým bajtům požadavku — znovu serializovaný JSON změní bajty a podpis nebude sedět. Opakovaná doručení nesou stejné X-Tracio-Event-Id, takže podle něj deduplikujte.
Hlavičky u každého doručení
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Postaveno tak, aby se události neztrácely
Doručování běží na vyhrazené flotile a zdrojem pravdy je fronta, ne paměť procesu. Právě to dělá z at-least-once realitu: když uzel doručování zemře v půli cesty, událost je pořád ve frontě a vezme si ji jiný uzel.
Opakování, která sedí na skutečné výpadky
5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. První opakování se vejdou do minuty, takže krátký restart vaší služby vás nestojí nic. Každá pauza se losuje mezi polovinou uvedené hodnoty a celou, aby se opakování po výpadku nevrátila jednou salvou.
Automatické vypnutí, které se neplete
Webhook se vypne, jen když chyby zároveň dosáhnou prahu a trvají aspoň 15 minut v kuse — nával nahromaděných doručení během restartu integraci nezabije. 410 Gone vypíná okamžitě. Dashboard ukazuje důvod, kód odpovědi a tlačítko pro opětovné zapnutí.
Rotace tajemství bez mezery
Po rotaci zůstávají obě tajemství platná 24 hodin a hlavička nese oba podpisy, takže stačí shoda kteréhokoli z nich. Konfiguraci si upravíte uvnitř okna, místo abyste závodili s přepnutím; „Odvolat teď“ okno zkrátí, když ho potřebujete uzavřít hned.
Log doručení, který si přečtete
Každý pokus — kód odpovědi, trvání, text chyby — je vidět u každého webhooku v dashboardu, vedle testovací akce, která pošle na váš endpoint podepsaný vzorový payload, abyste si ověřili svůj ověřovač dřív, než půjdete do ostrého provozu.
Zeptejte se ve chvíli, kdy se rozhodujete
Privátní API mezi servery na api.tracio.ai. Váš backend se ověří tajným klíčem a čte svoje vlastní data. Záměrně neposílá žádné CORS hlavičky: tajný klíč dává přístup ke všemu ve vašem pracovním prostoru a nikdy se nesmí dostat do prohlížeče. Dostupné od plánu Pro.
| Metoda | Cesta | Vrací |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Souhrn o návštěvníkovi: první a poslední výskyt, počet návštěv, unikátní IP a země, prohlížeče a zařízení, historie rizika — plus jeho poslední relace. |
| GET | /v1/visitors/{visitorId}/sessions | Seznam relací s kurzorovým stránkováním a filtry podle rozsahu dat, výsledku detekce botů a minimálního skóre rizika. |
| GET | /v1/visitors/{visitorId}/sessions/latest | Poslední relace jako jediný objekt, bez obálky seznamu. |
| GET | /v1/sessions/{requestId} | Jedna konkrétní relace. Přiložte k ní visitorId a vyhledání půjde přes index návštěvníka místo přes celou vaši historii. |
| GET | /v1/visitors/{visitorId}/velocity | Aktivita za okno — 1h, 24h nebo 7d: kolik návštěv, z kolika IP, z kolika zemí, pod kolika účty. |
Kontrola návštěvníka u pokladny
Typické volání: uvnitř vaší platební obsluhy, dřív než autorizujete kartu. Jeden požadavek, jedna odpověď — a blok meta hlásí okno, které jste skutečně dostali: když si řeknete o půl roku a váš plán uchovává 30 dní, vrátí 30 dní a řekne to.
Požadavek
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Odpověď
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Stejná čísla všude
Návštěva, která má ve vašem dashboardu 65,9, má 65,9 i v Data API a 65,9 v těle webhooku. Dvě nezávislá vykreslení by se mohla rozejít — klasicky přes škály, kdy vám jeden kanál podá 0,93 tam, kde druhý říká 93 — proto test parity postaví jednu návštěvu, vykreslí ji oběma kanály a porovná veřejná pole nad surovým JSON. Shoda je vynucená, ne tvrzená.
Rada, ne jen čísla
Skóre vám řeknou, co jsme viděli. Guidance vám řekne, co s tím dělat, pro čtyři rozhodnutí, která opravdu stojí peníze — spočítané verzovanými pravidly, s přiloženým zdůvodněním.
Přijmout platbu?
Zváží riziko, podvodnou reputaci a verdikt o botech dřív, než autorizujete kartu.
Přijmout registraci?
Zachytí jednorázový účet dřív, než vznikne — multi-accounting a reputace tu váží nejvíc.
Pustit dovnitř?
Automaticky přitvrdí, když se na návštěvě spustil detektor převzetí účtu.
Započítat konverzi?
Odliší skutečné doporučení od doporučení sebe sama nebo od placeného bota.
Slovník o čtyřech slovech
Každý scénář dostane jednu ze čtyř odpovědí a s ní i podklad, na kterém byla vydána — rozhodující osy z pevného slovníku: boti, riziko, podvodná reputace, chování, multi-accounting, převzetí účtu, síť, partnerský vzorec. Vždycky víte, která osa radu posunula, aniž byste kdy viděli jména signálů, váhy nebo prahy.
Jeden výpočet, tři kanály
Tentýž blok guidance jede ve webhooku, odpovídá v Data API a vykresluje se na kartě návštěvníka v dashboardu — jedna sada pravidel, jeden výsledek, žádné dorovnávání na vaší straně. Čtěte radu pro svůj scénář, ne celkovou: celková je prostě nejpřísnější ze čtyř, souhrn pro dashboardy, ne rozhodnutí o platbě. Verze pravidel jede v payloadu, takže změnu pravidel zaznamenáte, místo abyste ji odvozovali z rady, která se najednou pohnula.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Pět SDK na frontendu, dva kanály na backendu
Prohlížečová strana se dodává jako pět SDK — vanilla JavaScript, React, Vue 3, Angular a Svelte 5. Serverová SDK nejsou a je to záměr: váš backend se integruje přes prosté HTTP pomocí podepsaných webhooků a Data API. Ověření podpisu je tucet řádků proti referenčnímu vektoru, který zveřejňujeme, a ve stromu serverových závislostí nezůstává nic navíc, co byste museli pořád aktualizovat.
Často kladené otázky
Zapojte to během jednoho odpoledne
Vytvořte v dashboardu webhook, nasměrujte ho na svůj endpoint a dejte Test. Ověřte podpis proti našemu referenčnímu vektoru a to nejtěžší máte za sebou.