Czy potrzebuję webhooków, jeśli używam już Data API?

Nie, ale większość zespołów prowadzi jedno i drugie. Data API odpowiada o wizytę, na którą właśnie patrzysz; webhooki mówią ci o wizytach, na które nie patrzysz — atak botów o trzeciej w nocy, przejęcie konta w sesji, której nikt nie obserwuje. Webhooki niosą też późniejsze fazy: werdykt poprawiony przez wolniejsze dowody przychodzi jako nowe dostarczenie.

Co się stanie, jeśli mój endpoint nie działa?

Ponawiamy po rozszerzającej się drabinie — 5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h — osiem prób rozłożonych na mniej więcej 4,4 do 8,7 godziny, każda przerwa losowana, żeby ponowienia nie przyszły jedną salwą. Restart trwający minutę nic cię nie kosztuje, a webhook wyłączamy dopiero po serii błędów, która jednocześnie osiąga próg i trwa co najmniej 15 minut z rzędu.

Czy muszę weryfikować oba podpisy?

Dla większości integracji weryfikacja HMAC wystarczy i działa na obu schematach ładunku. Podpis platformy Ed25519 jest mocniejszą opcją — klucz publiczny zamiast wspólnego sekretu — i jedzie ze schematem 2. Jeśli twój weryfikator go wymaga, przepuść dostarczenia testowe z panelu: są z założenia wyłącznie na HMAC, bo klucz prywatny platformy nigdy nie opuszcza węzłów dostarczających.

Czy Data API i webhook mogą się nie zgadzać co do tej samej wizyty?

Mogą się różnić i nie jest to sprzeczność. Data API odpowiada z rekordu głównego — z tego, co było wiadomo przy wczytaniu strony. Późniejsze fazy docierają do ciebie jako dostarczenia webhooków i nie są z powrotem do niego scalane. Odpowiadają na różne pytania: co wiedzieliśmy w tamtej chwili, wobec tego, do czego doszliśmy, gdy dowody wciąż napływały. Jeśli działasz kilka minut po wizycie, ufaj tej fazie, którą dostałeś ostatnią.

Jakiego planu potrzebuję?

Webhooki zaczynają się od Pro — pięć na przestrzeń roboczą, 20 na Business, 100 na Enterprise. Data API jest od Pro w górę. Guidance, kody przyczyn werdyktu, sygnały behawioralne i dane urządzenia między przeglądarkami są od Business w górę.

Dostarczanie danych

Twoje dane tam, gdzie podejmujesz decyzję

Każda identyfikacja może dotrzeć do twoich systemów na dwa sposoby: przyjść na twój serwer w chwili, gdy się dzieje, albo zostać przez ciebie pobrana dokładnie w sekundzie, w której decydujesz. Oba kanały niosą te same liczby — pilnuje tego test, a nie obietnica.

Wypróbuj za darmo Umów demo

Dwa kanały

Push albo pull

Webhooki wypychają do ciebie zdarzenia w miarę, jak się dzieją. Data API pozwala zapytać w chwili, gdy potrzebujesz odpowiedzi. Większość zespołów prowadzi jedno i drugie: webhooki do zapisu i reakcji, Data API do sprawdzenia w locie.

Webhooki — push, w czasie rzeczywistym

Wysyłamy POST z podpisanym zdarzeniem JSON na twój endpoint w chwili, gdy coś się dzieje: odwiedzający zostaje zidentyfikowany, oznaczone zostaje przejęcie konta, zaczyna się atak botów. Nie ma czego odpytywać ani czego planować.

Najlepsze do: zapisywania każdej wizyty, reagowania na ataki, zasilania hurtowni danych albo SIEM.

Opóźnienie dostarczenia p50 44–140 ms, od zdarzenia do twojego endpointu.

Data API — pull, na żądanie

Prywatne API między serwerami. Twój backend uwierzytelnia się kluczem tajnym i czyta dokładnie to, co wiemy o odwiedzającym, w sekundzie, w której podejmuje decyzję — zwykle wewnątrz obsługi logowania albo płatności.

Najlepsze do: sprawdzenia w locie, zanim obciążysz kartę, zatwierdzisz rejestrację albo odblokujesz konto.

Dostępne od planu Pro.

Webhooki

Cztery typy zdarzeń, jedna koperta

Każde dostarczenie przychodzi w tej samej kopercie, z typem zdarzenia w treści i w nagłówku X-Tracio-Event-Type — więc jedna obsługa może rozdzielić wszystkie cztery.

Odwiedzający zidentyfikowany

Zdarzenie podstawowe: wizyta została oceniona. Niesie ID odwiedzającego, przeglądarkę i system, geolokalizację i sieć, werdykt o botach oraz decyzję o ryzyku. Dostarczane fazami — zdarzenie główne przy wczytaniu strony, potem faza późna albo korygująca, gdy wolniejsze dowody zmienią werdykt. Fazy powiążesz po requestId.

identification

Przejęcie konta

Na wizycie odpalił detektor przejęcia konta: urządzenie stojące za znanym kontem nie wygląda już jak urządzenie jego właściciela. Przychodzi jako własne zdarzenie, z dołączonym kontekstem konta, zamiast chować się w treści identyfikacji.

account_takeover

Atak botów

Skok ruchu zautomatyzowanego w twojej przestrzeni roboczej. Za tym zdarzeniem nie stoi żadna wizyta — to alert na poziomie przestrzeni roboczej, więc bloki wizyty są w treści po prostu nieobecne, zamiast przychodzić jako puste skorupy z wyzerowanymi ocenami.

attack_detected

Zmiana reputacji

Profil przeszedł między pasmami reputacji. Ta sama koperta co przy alercie o ataku — zdarzenie na poziomie profilu bez dołączonej wizyty, niosące nowe pasmo i poprzednie.

reputation_changed

Dostarczenie, w skrócie

To jest treść bazowa. Pro dokłada prędkość wizyt; Business dokłada do dokładnie tego samego kształtu kody przyczyn werdyktu, sygnały behawioralne, guidance i dane urządzenia między przeglądarkami — nowe bloki się pojawiają, istniejące ścieżki nigdy się nie przesuwają.

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

Każde żądanie niesie dwa podpisy

X-Tracio-Signature to HMAC-SHA256 po znaczniku czasu podpisu sklejonym z surową treścią żądania, kluczowany twoim sekretem webhooka — dowodzi, że nadawca zna sekret, który macie oboje. X-Tracio-Signature-Ed25519 to podpis platformy: weryfikujesz go kluczem publicznym pobranym z endpointu well-known, więc po twojej stronie nie ma czego trzymać w tajemnicy. Znacznik czasu wchodzi w podpisywaną treść i właśnie to sprawia, że stare przechwycone żądanie nie nadaje się do ponownego wysłania.

Weryfikuj po surowych bajtach żądania — ponownie zserializowany JSON zmienia bajty i podpis się nie zgodzi. Ponowienia niosą to samo X-Tracio-Event-Id, więc deduplikuj po nim.

Nagłówki przy każdym dostarczeniu

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

Niezawodność

Zbudowane tak, by nie gubić zdarzeń

Dostarczanie działa na dedykowanej flocie, a źródłem prawdy jest kolejka, a nie pamięć procesu. To właśnie czyni at-least-once realnym: jeśli węzeł dostarczający padnie w locie, zdarzenie wciąż jest w kolejce i przejmuje je inny węzeł.

zdarzeń na sekundę przez pojedynczy webhook, wobec około 50 przed lipcową przebudową

44–140 msopóźnienie dostarczenia p50 od zdarzenia do twojego endpointu

prób dostarczenia po rozszerzającej się drabinie, rozłożonych nawet na 8,7 godziny

z 90 000 zdarzeń dostarczono w ćwiczeniu, w którym pod obciążeniem zabito węzeł dostarczający

Ponowienia dopasowane do prawdziwych awarii

5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. Pierwsze ponowienia mieszczą się w minucie, więc krótki restart twojej usługi nic cię nie kosztuje. Każda przerwa jest losowana między połową podanej wartości a pełną, żeby ponowienia nie wróciły po awarii jedną salwą.

Automatyczne wyłączenie, które nie strzela na oślep

Webhook wyłączamy tylko wtedy, gdy błędy jednocześnie osiągną próg i trwają co najmniej 15 minut z rzędu — nawał zakolejkowanych dostarczeń podczas restartu nie zabije integracji. 410 Gone wyłącza natychmiast. Panel pokazuje powód, kod odpowiedzi i przycisk ponownego włączenia.

Rotacja sekretu bez przerwy

Po rotacji oba sekrety pozostają ważne przez 24 godziny, a nagłówek niesie oba podpisy, więc dopasowanie któregokolwiek wystarczy. Konfigurację aktualizujesz wewnątrz okna, zamiast ścigać się z przełączeniem; „Unieważnij teraz” skraca to okno, gdy trzeba je zamknąć od razu.

Dziennik dostarczeń, który da się czytać

Każdą próbę — kod odpowiedzi, czas trwania, treść błędu — widać przy każdym webhooku w panelu, obok akcji testowej, która wysyła na twój endpoint podpisany przykładowy ładunek, żebyś potwierdził swój weryfikator przed startem na produkcji.

Data API

Pytaj w chwili, w której decydujesz

Prywatne API między serwerami pod adresem api.tracio.ai. Twój backend uwierzytelnia się kluczem tajnym i czyta własne dane. Celowo nie wysyła nagłówków CORS: klucz tajny daje dostęp do wszystkiego w twojej przestrzeni roboczej i nigdy nie może trafić do przeglądarki. Dostępne od planu Pro.

Metoda	Ścieżka	Zwraca
GET	/v1/visitors/{visitorId}	Podsumowanie odwiedzającego: pierwsze i ostatnie wystąpienie, liczba wizyt, unikalne adresy IP i kraje, przeglądarki i urządzenia, historia ryzyka — plus jego najnowsza sesja.
GET	/v1/visitors/{visitorId}/sessions	Lista sesji ze stronicowaniem kursorowym i filtrami po zakresie dat, wyniku detekcji botów i minimalnej ocenie ryzyka.
GET	/v1/visitors/{visitorId}/sessions/latest	Najnowsza sesja jako pojedynczy obiekt, bez koperty listy.
GET	/v1/sessions/{requestId}	Jedna konkretna sesja. Podaj obok visitorId, a wyszukanie pójdzie przez indeks odwiedzającego zamiast przez całą twoją historię.
GET	/v1/visitors/{visitorId}/velocity	Aktywność w oknie — 1h, 24h albo 7d: ile wizyt, z ilu adresów IP, z ilu krajów, pod iloma kontami.

Sprawdzenie odwiedzającego przy płatności

Typowe wywołanie: wewnątrz twojej obsługi płatności, zanim autoryzujesz kartę. Jedno żądanie, jedna odpowiedź, a blok meta raportuje okno, które faktycznie dostałeś: jeśli poprosisz o pół roku, a twój plan przechowuje 30 dni, zwróci 30 dni i to napisze.

Żądanie

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"

Odpowiedź

JSON

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

Te same liczby wszędzie

Wizyta, która w twoim panelu ma 65,9, ma 65,9 w Data API i 65,9 w treści webhooka. Dwa niezależne renderowania mogłyby się rozjechać — klasycznie na skalach, gdy jeden kanał podaje ci 0,93 tam, gdzie drugi mówi 93 — więc test parzystości buduje jedną wizytę, renderuje ją oboma kanałami i porównuje pola publiczne na surowym JSON-ie. Zgodność jest wymuszona, a nie deklarowana.

Guidance — od planu Business

Rada, a nie same liczby

Oceny mówią, co zobaczyliśmy. Guidance mówi, co z tym zrobić, dla czterech decyzji, które naprawdę kosztują pieniądze — liczone przez wersjonowane reguły, z dołączonym uzasadnieniem.

Przyjąć płatność?

Waży ryzyko, reputację oszustw i werdykt o botach, zanim autoryzujesz kartę.

Przyjąć rejestrację?

Łapie konto jednorazowe, zanim powstanie — multikonta i reputacja ważą tu najwięcej.

Wpuścić?

Automatycznie się zaostrza, gdy na wizycie odpalił detektor przejęcia konta.

Zaliczyć konwersję?

Oddziela prawdziwe polecenie od polecenia samego siebie albo od opłaconego bota.

Słownik z czterech słów

allowNic, na co warto reagować.

challengePoproś o drugi składnik.

reviewWstrzymaj dla człowieka.

denyOdmów wprost.

Każdy scenariusz dostaje jedną z czterech odpowiedzi, a razem z nią podstawę, na której ją wydano — decydujące osie ze stałego słownika: boty, ryzyko, reputacja oszustw, zachowanie, multikonta, przejęcie konta, sieć, wzorzec partnerski. Zawsze wiesz, która oś przesunęła radę, nie widząc przy tym nazw sygnałów, wag ani progów.

Jedno obliczenie, trzy kanały

Ten sam blok guidance jedzie w webhooku, odpowiada w Data API i renderuje się na karcie odwiedzającego w panelu — jeden zestaw reguł, jeden wynik, żadnego uzgadniania po twojej stronie. Czytaj radę dla swojego scenariusza, a nie ogólną: ogólna to po prostu najostrzejsza z czterech, podsumowanie do paneli, a nie decyzja o płatności. Wersja reguł jedzie w ładunku, więc zmianę reguł zauważasz, zamiast wnioskować o niej z rady, która nagle się przesunęła.

JSON

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

Integracja

Pięć SDK na froncie, dwa kanały na backendzie

Strona przeglądarki dostarczana jest jako pięć SDK — vanilla JavaScript, React, Vue 3, Angular i Svelte 5. Nie ma SDK serwerowych i to jest celowe: twój backend integruje się po zwykłym HTTP przez podpisane webhooki i Data API. Weryfikacja podpisu to kilkanaście linii wobec wektora referencyjnego, który publikujemy, i w drzewie zależności serwera nie zostaje nic dodatkowego do ciągłego aktualizowania.

SDK przeglądarkowe

JavaScriptReactVue 3AngularSvelte 5

Przejrzyj SDK Dokumentacja API Dokumentacja webhooków

FAQ

Najczęściej zadawane pytania

Podłącz to w jedno popołudnie

Utwórz webhook w panelu, wskaż mu swój endpoint i naciśnij Test. Zweryfikuj podpis wobec naszego wektora referencyjnego i najtrudniejsze masz za sobą.

Wypróbuj za darmo Umów demo