Webhooks stellen Identifikationsereignisse in Echtzeit an Ihren Server zu. Jedes Mal,
wenn ein Besucher identifiziert wird, sendet TRACIO eine HTTP-POST-Anfrage an die
von Ihnen konfigurierte Webhook-URL. Der Anfragekörper ist der Ereignis-Payload.
Sie sind außerdem der einzige Kanal, der späte Verdicts zustellt — jene, bei denen das Verhalten eines Besuchers erst nach dem Laden der Seite bewiesen hat, dass er automatisiert war.
Richten Sie sie im Dashboard unter Settings → Webhooks ein. Webhooks erfordern den Pro-Tarif oder höher.
| Ereignis | Wann | Tarif |
|---|---|---|
identification | Bei jedem Besuch — die Phasen primary, late und correction | Alle |
account_takeover | Das Verhalten unter einem Konto passt nicht mehr zum Profil des Kontoinhabers | Business+ |
account_assessment | Der Bewertungsstand eines Kontos bei der Kontoübernahme: bewertet und unauffällig, bewertet und abweichend oder unbewertet | Business+ |
attack_detected | Ein Bot-Ausschlag auf Ihrer Website | Business+ |
reputation_changed | Die Reputation einer verknüpften Person ist in ein anderes Band gewechselt | Business+ |
transaction_state_changed | Das Ergebnis einer Transaktion, die Sie an POST /v2/transactions gesendet haben, hat sich geändert | Business+ |
login_risk | Eine Login-Bewertung durch POST /v2/logins/assess endete mit challenge oder review | Alle |
trusted_device_enrolled | Ein Gerät wurde für ein Konto als vertrauenswürdig eingetragen, oder sein Vertrauen wurde verlängert | Alle |
trusted_device_revoked | Das Vertrauen eines Geräts wurde widerrufen — über die API oder aus dem Dashboard | Alle |
affiliate_threshold_crossed | Die Empfehlung für einen Affiliate hat sich verschlechtert (none → review, none → hold, review → hold) | Alle |
Ereignisnamen verwenden Unterstriche, niemals Punkte — ein visitor.created oder
session.created gibt es nicht.
Ein Webhook abonniert bestimmte Typen; der gesonderte Wert * bedeutet „jeder Typ,
einschließlich später hinzugefügter“. Fünf Typen sind die Ausnahme: * umfasst
account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked und affiliate_threshold_crossed nicht — nennen Sie jeden
von ihnen ausdrücklich. account_assessment meldet Abdeckung statt eines Befunds
und kommt daher ungefähr einmal pro Besuch an, der eine linked_id trägt — eine
andere Größenordnung als bei den übrigen Ereignissen. Die Typen für Login-Risiko und
Affiliates ergeben nur für eine Integration Sinn, die diese APIs aufruft. Ein
Platzhalter, den Sie gesetzt haben, bevor es diese Ereignisse gab, ist keine
Zustimmung zu ihrem Empfang.
Ein unbekannter Typ wird beim Anlegen oder Bearbeiten eines Abonnements mit 400
abgelehnt, sodass ein Tippfehler Ihnen keinen Webhook hinterlassen kann, der
stillschweigend nie auslöst.
identificationEin einzelner Besuch erzeugt bis zu drei Zustellungen mit derselben request_id:
primary — das erste Verdict, beim Laden der Seite.late — Anreicherung rund neun Sekunden später, sobald die langsamen Prüfungen eingetroffen sind.correction — eine Korrektur auf Basis des Verhaltens (Zeiger, Tastatur, Scrollen).Korrelieren Sie sie über request_id und unterscheiden Sie sie über phase. Die
spätere Phase hat Vorrang: Sagte primary human und correction sagt bot, dann
ist die zweite die richtige Antwort.
Verlassen Sie sich nicht auf die Ankunftsreihenfolge. Jede Phase wird unabhängig
und mit eigenem Retry-Plan zugestellt — ging primary in einen Retry, während late
im ersten Anlauf erfolgreich war, erhalten Sie sie in umgekehrter Reihenfolge.
Bestimmen Sie den Vorrang über das Feld phase, nicht über den Empfangszeitpunkt.
Diese drei sind die einzigen Phasen eines identification-Ereignisses. Ein weiterer
Wert erreicht Sie: account_takeover und account_assessment tragen
phase: "beacon", denn beide werden aus dem Verhaltens-Beacon der Session ausgelöst.
Beachten Sie die Abweichung, die dadurch entsteht, denn sie betrifft die Idempotenz.
Eine produktive identification-Zustellung hat als event_id exakt
<request_id>:<phase>, doch andere Zustellungen brechen diese Formel. Ein
account_takeover lautet <request_id>:ato — das Suffix ist das Literal ato, nicht
der Wert des Feldes phase — und ein account_assessment lautet
<request_id>:ato-state-<state>. Eine aus dem Dashboard gesendete Test-Zustellung
lautet <request_id>:test, während phase in ihrem Körper weiterhin primary zeigt
— und ein Schema-1-Körper hat überhaupt kein Feld phase, sodass das Suffix
ausschließlich im Header auftaucht. Verwenden Sie event_id direkt als
Idempotenzschlüssel und setzen Sie ihn niemals aus request_id und phase neu
zusammen. Gleichen Sie gegen die Werte ab, die Sie verarbeiten, und ignorieren Sie
alles andere, statt die Zustellung abzulehnen.
Manche Ereignisse haben keinen Besuch: attack_detected (Workspace-Ebene),
reputation_changed (Personen-Ebene), transaction_state_changed
(Transaktions-Ebene), login_risk, trusted_device_enrolled und
trusted_device_revoked (Konto-Ebene) sowie affiliate_threshold_crossed
(Affiliate-Ebene). Sie haben weder request_id noch visitor_id und keinen der
Blöcke browser, geo, bot oder decision — diese Schlüssel fehlen schlicht,
ebenso wie der Header X-Tracio-Request-Id. account_takeover und
account_assessment dagegen werden von einem konkreten Besuch erzeugt und tragen den
vollständigen Identifikationskörper Ihres Tarifs. Wenn Sie alle Ereignisse in einem
Handler parsen, prüfen Sie event, bevor Sie Besuchsfelder anfassen.
Neue Webhooks verwenden die Payload-Version 3. Bestehende Webhooks auf Version 1 oder 2 behalten die gewählte Version; beide älteren Schemata sind eingefroren und werden am 2027-04-12 entfernt. Zur Migration wählen Sie Version 3 auf der Webhook-Karte im Dashboard.
| Version | Status |
|---|---|
1 | Eingefroren; wird am 2027-04-12 entfernt |
2 | Eingefroren; wird am 2027-04-12 entfernt |
3 | Voreinstellung für neue Webhooks; Schlüssel in snake_case |
Version 3 trägt dieselben Felder und Werte wie Version 2, mit Schlüsseln in
snake_case und einem version: 3 auf oberster Ebene. Der Signaturalgorithmus und die
Header bleiben unverändert (X-Tracio-Payload-Version: 3). Schlüssel in Ihrem eigenen
fields-Wörterbuch sind Ihre Daten und werden nicht umbenannt.
| 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", // Modell des Grafikadapters, normalisiert; fehlt, wenn unbekannt "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 // HTTP-Verkehr und der rohe Netzwerkpfad treten über verschiedene Netze aus }, "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}Null- und Leerwerte werden weggelassen. String- und Zahlenfelder mit dem Wert null
(zum Beispiel bot.type bei einem Menschen oder bot.antidetect_score: 0) fehlen im
JSON — machen Sie sie in Ihren Schemata nicht zur Pflicht und lesen Sie verschachtelte
Blöcke defensiv.
bot.score und decision.risk_score sind Dezimalwerte auf einer 0..100-Skala
mit einer Nachkommastelle — exakt die Zahlen, die das Dashboard und die Data-API für
denselben Besuch ausweisen. (Im eingefrorenen v1-Schema verwenden sie andere
Einheiten: einen Bruchteil 0..1 bzw. 0..255.)
bot.type ist entweder der Name eines erkannten Bots, ein verifizierter KI-Agent
(ai_agent:<vendor>) oder ein Familien-Label. Siehe
Bot-Typen für das Vokabular — interne Prüfnamen
werden nie offengelegt, in keinem Tarif. ai_agent:<vendor> bedeutet, dass die
Anfrage bewiesen hat, aus der Infrastruktur dieses Anbieters zu stammen — durch eine
gültige Web-Bot-Auth-Signatur mit einem Schlüssel, den der Anbieter veröffentlicht,
oder durch eine Adresse innerhalb der IP-Bereiche, die der Anbieter veröffentlicht —,
statt dies nur im User-Agent zu behaupten. Eine Anfrage, die sich als KI-Agent
ausgibt und der jeder vom Anbieter veröffentlichte Nachweis widerspricht, wird als
impersonation gemeldet.
| Feld | Typ | Beschreibung |
|---|---|---|
version | number | Version des Payload-Schemas (3) |
event | string | Ereignistyp |
event_id | string | Kennung der Zustellung — der Idempotenzschlüssel; eindeutig pro Ereignis und geteilt von allen Ihren Webhooks, die es empfangen, stabil über Retries hinweg |
request_id | string | Kennung des Besuchs (UUID), geteilt von allen seinen Phasen |
phase | string | primary, late, correction; account_takeover und account_assessment tragen beacon |
visitor_id | string | Stabile Besucherkennung |
linked_id | string | Vom Client gelieferte verknüpfte Kennung |
tag | string | Vom Client gelieferter benutzerdefinierter Tag |
fields | object | Benutzerdefinierte Felder, die dem Besuch bei der Erfassung angehängt wurden. Nur was mit dem Besuch eingetroffen ist — ein später über die Data-API angehängtes Feld erscheint nie in einem Webhook, in keiner Phase und bei keinem Retry. Schlüssel und Werte sind Strings. Fehlt, wenn der Besuch keine Felder mitbrachte |
timestamp | string | Ereigniszeitpunkt (RFC 3339) |
url | string | URL der Seite, auf der das Ereignis erfasst wurde |
ip | string | IP-Adresse des Clients |
user_agent | string | Roher User-Agent-String des Clients |
browser.name / .version | string | Erkannter Browser |
os.name / .version | string | Erkanntes Betriebssystem |
device | string | Geräteklasse (z. B. desktop, mobile) |
gpu | string | Modell des Grafikadapters, wie es der Browser meldet (WebGL), normalisiert auf einen lesbaren Namen (Intel Iris Xe Graphics, Apple M1 Pro); Software renderer bei Software-Rasterizern; fehlt, wenn unbekannt |
geo | object | IP-Geolokalisierung: country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (Booleans) und connection_type |
network.proxy_detected | boolean | Der HTTP-Verkehr des Besuchs und seine rohen Netzwerkpfade treten über verschiedene Netze aus — ein Proxy oder VPN vor dem Browser. Zwei Adressen desselben Anbieters (Carrier-NAT, ein zweiter Ausgang desselben VPN) zählen nicht |
bot.result | string | human, bot oder uncertain |
bot.type | string | Bot-Name, verifizierter KI-Agent oder Familien-Label, wenn ein Bot erkannt wurde |
bot.score | number | Bot-Score (0–100) |
identification.confidence | number | Identifikations-Konfidenz (0.0–1.0) |
identification.incognito | boolean | Privater/Inkognito-Browsing-Kontext |
decision.action | string | real, fake oder suspicious |
decision.risk_score | number | Aggregierter Risiko-Score (0–100) |
extensions | array | In diesem Besuch erkannte Browser-Erweiterungen als stabile maschinenlesbare Slugs (Namen, Kategorien und Store-Links finden Sie im Dashboard und in der Data-API). Fehlt, wenn nichts erkannt wurde |
Ab Pro — wie sich der Besucher über die Zeit verhält:
{ "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}Ab Business — warum das Verdict so ausgefallen ist:
{ "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, // die öffentliche Adresse, die auf dem rohen Netzwerkpfad beobachtet // wurde, also die Adresse hinter dem Proxy oder VPN; fehlt, wenn keine // solche Adresse beobachtet wurde "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // Die auf einem Linux-Rechner GEMESSENE Desktop-Umgebung ("Mint 22+", // "Ubuntu", "GNOME", "KDE"); ein User-Agent kann keine Distribution // ausdrücken. Fehlt, wenn nicht bestimmt — bei den meisten Linux-Besuchen // und bei jedem Nicht-Linux-Besuch. "os_environment": "Mint 22+", // Was der Besuch über sich selbst behauptet hat, verglichen mit dem, was // unabhängige Prüfungen gemessen haben. Nur vorhanden, wenn tatsächlich // ein Spoof erkannt wurde; ein leeres Feld `real` bedeutet "die Prüfung // blieb stumm", niemals "bestätigt". Bei der Achse `gpu` trägt // `claimed.gpu` den behaupteten Adapter als denselben lesbaren Modellnamen // wie das Feld `gpu` auf oberster Ebene. "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"] } }, // Gerätefakten — was der Browser des Besuchers über die Maschine meldet, // auf unserer Seite bereinigt. screen: Auflösung, Farbtiefe und das Device // Pixel Ratio. locale: die vom Browser selbst bevorzugten Sprachen und die // Zeitzone — im Unterschied zu geo.timezone, das aus der IP-Adresse // abgeleitet wird; eine Abweichung zwischen beiden ist ein häufiges // Anzeichen für einen vorgetäuschten Standort. client_hints: User-Agent // Client Hints — CPU-Architektur und Bitness, Gerätemodell (Android: der // Modellcode in `model`, z. B. "SM-A556B", und sein Marketingname aus der // Google-Play-Geräteliste in `device_name`, z. B. // "Samsung Galaxy A55 5G") und die genaue Plattformversion; nur // Chromium-basierte Browser melden sie. // Jeder Block fehlt, wenn der Besuch keine solchen Daten mitbrachte — // behandeln Sie daher jeden als optional. "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" }, // Nur vorhanden, wenn sich der Grafikadapter selbst als virtuell zu // erkennen gegeben hat; hypervisor ist ein geschlossenes Wörterbuch // (vmware, virtualbox, parallels, qemu, hyperv, bochs, intel-gvt, vgpu). // Ein fehlender Block bedeutet, dass es keinen solchen Hinweis gibt. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}Siehe Bot-Erkennung für das Vokabular der
Reason Codes und die Bedeutung von severity.
Felder für Multi-Accounting (ab Business). Sobald der Personenmodus für Ihren
Workspace aktiviert ist, trägt der Körper zusätzlich person_id, einen
reputation-Block (score, categories, overall_risk), linked_accounts_count
und linked_visitors_count — ob der Besucher mit anderen Besuchern und Konten
verknüpft ist. Die Personen-Ebene läuft derzeit im Beobachtungsmodus, und bis sie live
geht, fehlen diese Felder im Körper. Machen Sie sie in Ihren Schemata nicht zur
Pflicht.
guidance liefert fertige „Was tun“-Empfehlungen je Integrationspunkt, damit Sie
keine Policy aus Rohwerten ableiten müssen. Es ist in jedem v3-Ereignis ab Business
vorhanden — allow wird ausdrücklich angegeben:
{ "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 }}Jedes Szenario startet bei allow und bewegt sich immer nur nach oben auf der
Leiter: allow → challenge → review → deny. Innerhalb eines Szenarios gewinnt
die strengste auslösende Achse, und overall ist der strengste Wert über alle vier
Szenarien.
| Empfehlung | Zahlung | Registrierung | Login | Affiliate |
|---|---|---|---|---|
allow | Verarbeiten | Anlegen | Einlassen | Conversion gutschreiben |
challenge | 3-D Secure / Bestätigung | Captcha, Bestätigung per E-Mail oder Telefon | Step-up-2FA, erneut authentifizieren | Als zweifelhaft markieren, bis Aktivität sichtbar wird |
review | Verarbeiten, aber zur Prüfung einreihen | Mit Einschränkungen anlegen | Einlassen und Alarm auslösen | Auszahlung bis zur Prüfung zurückhalten |
deny | Transaktion nicht verarbeiten | Kontoerstellung ablehnen | Nicht einlassen | Conversion nicht gutschreiben |
basis listet die Achsen auf, die die Empfehlung bestimmt haben — eine Achse,
deren Vorschlag milder war als der übernommene, kommt nicht auf die Liste. Lesen Sie
sie nach Code, statt eine feste Menge anzunehmen:
Achse (basis) | Bedeutung |
|---|---|
list | Der Besucher hat eine Ihrer Workspace-Listen im Modus enforce getroffen. Eine allow-Liste übersteuert jede Achse: Jedes Szenario wird zu allow, und basis ist exakt ["list"] |
rule | Der Besuch hat eine Ihrer Workspace-Regeln im Modus enforce getroffen; eine Regel verschiebt nur die Empfehlung ihres eigenen Szenarios (eine allow-Regel mildert nur dieses eine) und wird übersprungen, wenn bereits eine Liste gegriffen hat |
bot | Der Bot-Detektor hat auf Automatisierung geschlossen — lehnt jedes Szenario ab |
risk | Die Entscheidung und der Gesamt-Risiko-Score des Besuchs |
behavior | Die Verhaltensbiometrie meldet mit ausreichender Konfidenz einen Bot — fügt Reibung hinzu statt einer Ablehnung |
account_takeover | Das Verhalten unter diesem Konto passt nicht mehr zum Profil seines Inhabers — Login auf challenge, Zahlung auf review |
network | Tor oder ein VPN, das aus einem Rechenzentrum austritt |
affiliate_pattern | Das Muster selbst erzeugter Empfehlungen — die Affiliate-Conversion wird als challenge zurückgehalten |
fraud_reputation, multiaccounting | Die Reputation und die Kontengruppierung der Person hinter dem Besucher; erscheinen, sobald die Personen-Ebene live ist |
version ist die Version des Regelwerks — sie wird erhöht, wenn sich die Logik
verbessert; halten Sie sie daher in Ihren Logs fest. Version 2 hat die Achse list
eingeführt, die erste, die eine Empfehlung mildern kann; Version 3 hat die
Login-Schwellen von account_takeover auf die Skala des Verdict-Scores der
Kontoübernahme verlegt, sodass derselbe Besuch deny erhalten kann, wo Version 2
challenge ergab, und umgekehrt.
Guidance ist additiv: Neue Szenarien kommen als neue Schlüssel hinzu, ohne den Vertrag
zu brechen. Die spätere Phase gewinnt, außer bei teilweisen Empfehlungen: Eine
Zustellung, die auf einer unvollständigen Eingabemenge berechnet wurde, ist mit
"partial": true gekennzeichnet, und eine teilweise Empfehlung überschreibt
keine vollständige Empfehlung, die zuvor für dieselbe request_id eingegangen
ist. In einer gewöhnlichen Zustellung fehlt das Feld partial vollständig.
Exakte Schwellenwerte werden bewusst nicht dokumentiert. Eine Empfehlung, die sich zu
einem Score zurückrechnen lässt, ist keine Absicherung mehr. Es gibt genau eine
bewusste Ausnahme: account_assessment.verdict.threshold, die Entscheidungsgrenze des
Verdicts zur Kontoübernahme, die unten beschrieben ist.
account_takeoverNur Business und Enterprise; in niedrigeren Tarifen wird keine Zustellung erzeugt,
selbst wenn ein Webhook dieses Ereignis abonniert hat. Der Körper ist der vollständige
Identifikations-Envelope Ihres Tarifs plus ein account_alert-Block und der im
nächsten Abschnitt beschriebene account_assessment-Block, höchstens einmal pro
Besuch zugestellt:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // der Alarm wird aus einem Beacon ausgelöst; nur die event_id sagt "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}Warum type eine Version trägt. Die Konstruktion hinter dem Score hat sich schon
geändert: die Skala und die Basis des Verdicts. behavior-drift/2 ist die erste
versionierte Konstruktion. Wenn Sie eigene Regeln auf die Zahl kalibriert haben,
werten Sie eine Änderung dieses Werts als Signal, sie erneut zu prüfen.
account_alert.drift_score und identification.drift_score sind dieselbe Zahl
(seit 2026-10-03): der geglättete Verhaltens-Score, auf dem das Verdict beruht,
gemessen am Ring der früheren vertrauenswürdigen Fenster des Kontoinhabers. Vor diesem
Datum trug identification.drift_score eine rohe Distanz auf einer anderen Skala —
mischen Sie Werte nicht über dieses Datum hinweg. Wurde ein Fenster nicht bewertet,
fehlt das Feld, statt null zu sein. Verwenden Sie account_assessment.verdict, wenn
Sie die Zahl zusammen mit dem Schwellenwert brauchen, mit dem sie verglichen wurde.
In v1 heißt der Block accountAlert mit type, linkedId und drift, und es gibt
keinen Bewertungsblock. In v2 benennt der Alarm zwei Felder um — linkedId →
accountId und drift → driftScore — und fügt accountAssessment hinzu; v3
verwendet die obigen Namen in snake_case. Aktualisieren Sie Ihren Handler, wenn Sie
die Version wechseln, sonst sieht Ihre Kontoübernahme-Logik die Daten
stillschweigend nicht mehr.
account_assessmentNur Business und Enterprise. Erfordert ein ausdrückliches Abonnement: * umfasst es
nicht.
Ohne dieses Ereignis bedeutet das Ausbleiben eines Alarms zwei verschiedene Dinge zugleich: Entweder haben wir die Session gegen das Profil des Kontoinhabers bewertet und sie passte, oder wir konnten sie gar nicht bewerten — das Profil des Inhabers ist nicht bereit, das Fenster war zu dünn, oder der Verkehr stammte nicht von einer Person. Beides sieht wie Stille aus, und Stille liest sich als Sicherheit. Meist ist sie es nicht: An einem vollen Produktionstag im September 2026 haben wir uns bei 73 % der Fenster und 80 % der Konten eines Verdicts enthalten. Ein Prozess, der auf „kein Alarm heißt alles in Ordnung“ aufbaut, baut auf einem Zustand auf, den wir überwiegend nicht haben.
{ "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 fehlt nie und ist nie leer:
state | Bedeutung | Was tun |
|---|---|---|
assessed_clear | Bewertet; das Verhalten passt zum Inhaber | Nichts |
assessed_alert | Bewertet; das Verhalten weicht ab | Step-up — der Alarm account_takeover trägt dasselbe Verdict |
not_assessed | Es wurde kein Verdict gefällt | Nicht als unauffällig behandeln; auf eigene Signale zurückgreifen |
reason (nur bei not_assessed):
reason | Bedeutung |
|---|---|
profile_not_ready | Die Referenz des Inhabers kann für dieses Konto derzeit kein Verdict liefern. Behandeln Sie das als Zustand, nicht als Etappe: Er kann sich nie ändern, warten Sie also nicht |
profile_learning | Die Referenz wird noch aufgebaut |
window_too_sparse | Eine Person war da, aber das Fenster enthielt zu wenig Interaktion |
not_computable | Fenster und Referenz hatten keine informativen Achsen gemeinsam |
bot_traffic | Es gab genug Daten, und es gab keine Person, die zu bewerten war |
Seit 2026-10-04 18:00 UTC werden window_too_sparse und not_computable für einen
Inhaber mit bereiter Referenz nicht mehr ausgegeben — ein solches Fenster wird als
profile_not_ready gemeldet. Die beiden Gründe bleiben in der Liste, weil frühere
Zustellungen sie tragen: Wenn Ihr Handler nach ihnen verzweigt, leiten Sie
profile_not_ready genauso, und vergleichen Sie die Raten dieser Gründe nicht über
dieses Datum hinweg.
state und reason sind nicht an den Tarif gebunden. verdict gibt es ab Business,
wie drift_score.
Der Block verdict ist nur bei assessed_clear und assessed_alert vorhanden.
Bei not_assessed fehlt der Block, statt mit Nullen gefüllt zu sein — ein score
von 0 neben einem threshold von 0 würde sich als „Verhalten passte exakt“ lesen.
| Feld | Bedeutung |
|---|---|
severity | low oder high — bewusst zwei Bänder: Ein mittleres Band bräuchte einen zweiten Schwellenwert auf derselben Skala |
score | Der Wert, auf dem das Verdict beruht |
threshold | Der Wert, mit dem er tatsächlich verglichen wurde |
scale | Wie der Score gebildet wird: manhattan-normalized ist d/(1+d) in einem normalisierten Verhaltensraum, wobei 0 exakte Übereinstimmung bedeutet |
basis | ring — Distanz zum nächsten der früheren vertrauenswürdigen Fenster des Inhabers; centroid — Distanz zu seinem gemittelten Profil |
windows | Wie viele Fenster in den Score eingeflossen sind |
score und threshold stehen immer auf derselben, benannten Skala, sodass das Paar
die Entscheidung reproduziert: Der Alarm löst genau dann aus, wenn
score > threshold.
Wie oft es ankommt. Höchstens eine Zustellung pro Zustand und Besuch — in der
Praxis eine pro Besuch, der eine linked_id trägt, nicht eine pro Verhaltensfenster.
Ein Zustand kann sich innerhalb eines Besuchs ändern — zum Beispiel schließt die
Referenz ihr Lernen ab und not_assessed wird zu assessed_clear —, und dann
erhalten Sie beide, in dieser Reihenfolge. Dieser Übergang ist möglich, nicht
zugesagt: profile_not_ready kann über die gesamte Lebensdauer des Kontos bestehen
bleiben.
Was es nicht verspricht. Am besten geschützt sind aktive Nutzer mit langen Sessions und einem vollständigen Referenzprofil; am schlechtesten geschützt sind seltene Nutzer, für die eine Übernahme gefährlicher ist. Das ist eine Eigenschaft der Konstruktion, kein Schwellenwert, der sich einstellen lässt. Das Ereignis meldet eine Verhaltensabweichung von einer Referenz — es ist kein Anspruch, Kontoübernahmen im Allgemeinen zu erkennen.
attack_detectedDer Alarm über einen Bot-Ausschlag kommt im gemeinsamen v3-Envelope mit einem
attack-Block an. Er hat keine Identifikationsfelder — es ist ein Ereignis auf
Workspace-Ebene:
{ "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 }}Webhooks auf Payload-Version 1 erhalten das historische flache Alarmschema — es ändert sich nicht.
login_risk, trusted_device_enrolled und trusted_device_revokedDiese drei Ereignisse entstehen aus Ihren eigenen Aufrufen der Login-Risiko-API
(POST /v2/logins/assess) und ihrer vertrauenswürdigen Geräte. Sie werden nur bei
einem ausdrücklichen Abonnement mit Namen zugestellt — * umfasst sie nicht — und
nur an Webhooks auf Payload-Version 2 oder 3; Version 1 hat für sie keinen Körper.
login_risk wird gesendet, wenn eine Bewertung challenge oder review liefert —
nie bei allow, deny oder not_assessed. Sein login_risk-Block ist die
gespeicherte Bewertung, genau so, wie die synchrone Antwort sie geliefert hat.
Event-ID: login-risk:<id>, wobei <id> unsere Kennung des gespeicherten
Datensatzes ist — Ihre eigene assessment_id entnehmen Sie dem Körper.trusted_device_enrolled und trusted_device_revoked werden bei jeder Eintragung,
Verlängerung und jedem Widerruf eines vertrauenswürdigen Geräts gesendet. Ihr
trusted_device-Block — user_id, device_ref, enrolled_at, expires_at,
revoked_at, revoked_by (api oder dashboard) — ist eine Momentaufnahme zum
Zeitpunkt des Ereignisses; bei trusted_device_enrolled sind revoked_at und
revoked_by null. Event-ID: trusted-device:<n>.Sie werden asynchron gesendet, bis zu etwa fünf Sekunden nach dem Aufruf, und tragen
keinen Header X-Tracio-Request-Id — verwenden Sie login_risk.request_id, um den
Besuch zu finden. Der Webhook ist eine Benachrichtigung für Audit und Alarmierung; die
Entscheidung selbst ist die synchrone Antwort.
{ "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_crossedWird nur bei einem ausdrücklichen Abonnement mit Namen zugestellt — * umfasst es
nicht — und nur an Webhooks auf Payload-Version 2 oder 3. Alle 15 Minuten berechnet
TRACIO den Qualitäts-Score jedes Affiliates mit ausreichend Daten neu und sendet das
Ereignis, wenn sich seine Empfehlung verschlechtert: none → review, none → hold
oder review → hold. Eine Verbesserung sendet nichts und erlaubt, die nächste
Verschlechterung erneut zu melden. Das Ereignis gehört zum Workspace: Es geht an die
abonnierten Webhooks jeder Umgebung und trägt keinen 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 sind die Anteile des Affiliates über die letzten 90 Tage, dieselben, die der
Bericht im Dashboard zeigt: der Anteil der Registrierungen, die eine erste Einzahlung
erreicht haben (reg_to_ftd), der Anteil der Spieler, die 14 Tage nach der
Registrierung noch aktiv sind (active14_share), sowie die Anteile der Conversions
mit doppeltem Gerät oder doppelter Person, aus einem Betrugsring, von Bonusjägern, aus
einem Rechenzentrum, VPN oder von einem Bot, als Chargeback oder als Affiliate-Betrug
markiert und ohne gefundenen Besuch. TRACIO gibt nur Empfehlungen — die Zurückhaltung
selbst und jede Auszahlungsentscheidung bleiben in Ihrer Affiliate-Plattform. Auf
Payload-Version 2 hat derselbe Körper Schlüssel in camelCase: Der Block heißt
affiliateThreshold, mit affiliateId, previousRecommendation, qualityScore und
so weiter.
transaction_state_changedAb Business. Wird gesendet, wenn sich das Ergebnis einer Transaktion ändert, die Sie
an POST /v2/transactions gesendet haben: Die Regeln haben REVIEW oder DECLINE
entschieden (ein APPROVE sendet nichts), ein Analyst hat die Transaktion im
Dashboard zur Prüfung geschickt, oder ein Label wurde gesetzt, ersetzt oder entfernt.
Nutzen Sie es, um einen Bonus zurückzuhalten, solange ein Anspruch geprüft wird, und
ihn einzubehalten oder freizugeben, sobald das Ergebnis feststeht — ohne Polling. *
umfasst dieses Ereignis; es wird nur an Webhooks auf Payload-Version 2 oder 3
zugestellt. Ein an eine Umgebung gebundener Webhook erhält es nur für diese Umgebung.
{ "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 }}| Schlüssel | Bedeutung |
|---|---|
effective_state | Das Ergebnis, nach dem Sie handeln: der Zustand des Analysten oder des Labels, wenn einer gesetzt ist, sonst state |
recommendations | Was mit dem Bonus zu tun ist, abgeleitet aus effective_state |
label, label_source, label_at | Das aktuelle Label, wo es gesetzt wurde (api oder dashboard) und wann; alle drei sind null, wenn die Transaktion kein Label hat |
previous_effective_state | effective_state vor dieser Änderung; null für das Ereignis, das bei der automatischen Entscheidung gesendet wird |
Der Block zeigt die Transaktion so, wie sie beim Senden des Ereignisses ist:
Folgen zwei Änderungen schnell aufeinander, tragen beide Ereignisse den neuesten
Zustand, jeweils mit eigenem previous_effective_state und timestamp. Die
Reihenfolge ist nicht garantiert — sortieren Sie nach timestamp und lesen Sie die
Transaktion über die API, um ihren aktuellen Zustand zu erfahren. Event-ID:
txn-state:<id>:created für die automatische Entscheidung und txn-state:<id>:<n>
für jede spätere Änderung. Das Ereignis sagt nicht, wer ein Label gesetzt hat — nur,
woher es kam.
reputation_changedAb Business. Wird gesendet, wenn die kundenübergreifende Reputation einer Person, die
Ihre Organisation gesehen hat, in ein anderes Band wechselt (zum Beispiel clean →
suspicious). Es setzt die Personen-Ebene voraus, die derzeit im Beobachtungsmodus
läuft — daher feuert das Ereignis nur für Workspaces, in denen die
geräteübergreifende Identitätsauflösung aktiviert ist. Es ist ein Ereignis auf
Personen-Ebene: Es hat keine request_id und keine Besuchsblöcke.
{ "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 }}Der Blockschlüssel ist reputation_change, nicht reputation: Letzterer ist für die
Reputation im Kontext eines konkreten Besuchs vergeben, und das sind zwei verschiedene
Dinge. Schema 1 liefert die historische flache Form — dieselben Felder auf oberster
Ebene.
Jede Zustellung enthält einen X-Tracio-Signature-Header:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t ist der Unix-Zeitstempel (in Sekunden), zu dem die Anfrage signiert wurde.v1 ist der hex-kodierte HMAC-SHA256 von "<t>.<rawRequestBody>", geschlüsselt mit
Ihrem Webhook-Secret.Der Zeitstempel ist Teil des signierten Inhalts, was Replay-Schutz bietet.
Zwei Dinge müssen stimmen, sonst schlägt die Verifizierung in Produktion fehl:
v1=-Wert. Während einer
Secret-Rotation trägt der Header zwei Signaturen, und ein Parser, der nur eine
davon behält, weist während des gesamten Rotationsfensters gültige Zustellungen ab.// 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")})Zustellungen nach Schema 2 und 3 tragen zusätzlich X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Beide Seiten kennen das HMAC-Secret; der HMAC
beweist also, dass der Absender das Secret kennt, aber nicht, dass die Anfrage von
TRACIO stammt — die asymmetrische Signatur tut das. Die öffentlichen Schlüssel werden
unter https://api.tracio.ai/.well-known/webhook-keys veröffentlicht, indiziert nach
kid: Lesen Sie das Feld public_key. Der veraltete Alias publicKey trägt
denselben Wert und wird am 2027-04-12 entfernt.
Test-Zustellungen aus dem Dashboard werden nur mit HMAC signiert — der private
Plattform-Schlüssel liegt auf den Zustellknoten und steht dem Dashboard bewusst nicht
zur Verfügung. Ein Verifizierer, der Ed25519 hart voraussetzt, muss
Test-Zustellungen durchlassen (sie tragen das Suffix :test an der event_id),
sonst scheitern Tests aus dem Dashboard, während die Produktion einwandfrei läuft.
Dieselbe Vorsicht gilt für Formatprüfungen: Eine Test-Zustellung trägt die
request_id in der Form test_<hex> und als visitor_id das Literal
test_visitor — ein Handler, der diese gegen die Produktionsformen validiert, weist
damit eine ansonsten wohlgeformte Zustellung ab.
Nach einer Rotation bleiben beide Secrets 24 Stunden lang gültig und der Header trägt beide Signaturen, sodass Sie Ihre Konfiguration ohne Zustellverluste aktualisieren können. Die Aktion Revoke now verkürzt das Fenster. Aktualisieren Sie das Secret auf Ihrer Seite innerhalb von 24 Stunden: Sobald das Fenster schließt, passt das alte Secret nicht mehr, und wenn Ihr Endpunkt auf eine ungültige Signatur mit 4xx antwortet, deaktivieren fünf solche Antworten in Folge den Webhook.
| Header | Beschreibung |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — zwei v1= während eines Rotationsfensters |
X-Tracio-Signature-Ed25519 | Plattform-Signatur, t=<unix>,kid=<id>,v1=<base64> (nur v2 und v3) |
X-Tracio-Event-Id | Kennung der Zustellung — der Idempotenzschlüssel |
X-Tracio-Request-Id | Kennung des Besuchs, entspricht request_id (nur v2 und v3). Wird nur für Besuchsereignisse gesendet — identification, account_takeover und account_assessment |
X-Tracio-Event-Type | Der Ereignistyp (nur v2 und v3) |
X-Tracio-Delivery-Attempt | Versuchsnummer, beginnend bei 1 (nur v2 und v3) |
X-Tracio-Payload-Version | 3 oder 2 (nur v2 und v3) |
X-Tracio-Webhook-Id | Kennung des Webhooks, der diese Zustellung erzeugt hat |
Zustellungen können wiederholt werden, und eine Wiederholung trägt dieselbe
X-Tracio-Event-Id. Deduplizieren Sie darüber:
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")})Beachten Sie, dass event_id pro Ereignis eindeutig ist, nicht pro Webhook: Wenn
mehrere Webhooks im Workspace dasselbe Ereignis abonniert haben, erhält jeder eine
Zustellung mit derselben Kennung. Für identification wird sie als
<request_id>:<phase> gebildet, weshalb die drei Phasen eines Besuchs unabhängig
voneinander dedupliziert werden, statt zu einer einzigen zu verschmelzen. Ereignisse
ohne Besuch haben eigene Formen — siehe das jeweilige Ereignis oben.
Antworten Sie mit 2xx — das ist das einzige Zeichen, dass eine Zustellung angenommen wurde.
| Antwort | Was passiert |
|---|---|
2xx | Zustellung abgeschlossen |
429 Too Many Requests | Zählt nicht als Fehlschlag und verbraucht keinen Versuch; ein längeres Retry-After wird beachtet |
408, 425, 5xx, abgebrochene Verbindung | Wiederholung mit wachsender Pause |
410 Gone | Der Endpunkt gilt als entfernt — der Webhook wird sofort deaktiviert |
Andere 4xx | Wiederholung, aber fünf in Folge deaktivieren den Webhook — 400/401/404 heilen nicht durch Retry |
Retry-Plan: 5 s → 30 s → 2 min → 10 min → 30 min → 2 h → 6 h (8 Versuche). Die ersten Retries passen in eine Minute, ein kurzer Neustart Ihres Dienstes kostet Sie also keine Benachrichtigung. Jede Pause wird zwischen der Hälfte und dem vollen Wert randomisiert, damit Retries nach einem Ausfall nicht in einer einzigen Salve losgehen.
Die automatische Deaktivierung erfordert sowohl einen Schwellenwert (20 aufeinanderfolgende Fehlschläge oder 5 Konfigurationsfehler) als auch mindestens 15 aufeinanderfolgende Minuten mit Fehlschlägen — ein kurzer Neustart kann die Integration selbst dann nicht killen, wenn viele Zustellungen in der Warteschlange lagen. Eine Lücke von mehr als 15 Minuten setzt die Zählung zurück. Das Dashboard zeigt den Grund mit Antwortcode und Fehlertext sowie eine Schaltfläche Re-enable, die die Zähler zurücksetzt.
| Tarif | Webhooks pro Workspace |
|---|---|
| Free | Nicht verfügbar |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Endpunkte müssen https mit öffentlicher IP sein — private Adressen und
Loopback-Adressen werden abgelehnt, auch bei einer Weiterleitung — und dürfen nicht
tiefer als zwei Weiterleitungen sein.
Nur 307- und 308-Weiterleitungen werden verfolgt. 301, 302 und 303 weisen
den Client an, auf GET zu wechseln und den Körper zu verwerfen; eine Zustellung folgt
ihnen daher nicht, und der Versuch zählt als fehlgeschlagen. Wenn Ihr Load Balancer die
URL normalisiert (etwa www oder einen abschließenden Schrägstrich ergänzt), richten
Sie den Webhook direkt auf die finale URL.
Webhooks werden im Dashboard verwaltet. Das Dashboard steuert eine
Workspace-scoped Management-API, die auf dem Anwendungs-Host bereitgestellt wird (zum
Beispiel https://app.tracio.ai/api/v1); die Endpunkte unten sind genau die, die es
aufruft. Jeder Webhook-Endpunkt liegt unter /workspaces/{wsId}.
Das ist keine Server-zu-Server-Schnittstelle. Die Management-API akzeptiert ausschließlich das JWT Ihrer Dashboard-Session, geprüft gegen Ihre Workspace-Rolle (RBAC); ein Secret Key
tracio_sk_…wird hier abgelehnt. Da diese Session im Browser lebt und mit ihm abläuft, verstehen Sie die folgenden Aufrufe als Beschreibung dessen, was das Dashboard tut, und nicht als zu automatisierende Integration. Für programmatischen Zugriff aus Ihrem eigenen Backend nutzen Sie die schreibgeschützte Data-API.
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": [] }'Das Signing-Secret wird von TRACIO erzeugt und einmalig beim Anlegen (und beim
Rotieren) unter signingSecret zurückgegeben. Bewahren Sie es sicher auf — es ist der
Schlüssel, mit dem Sie Signaturen verifizieren.
{ "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" }}Bei späteren Lesezugriffen ist das signingSecret maskiert (null) — es wird nur beim
Anlegen und beim Rotieren des Secrets offengelegt.
| Methode | Pfad | Beschreibung |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Webhooks auflisten |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | url / events / status aktualisieren |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Einen Webhook löschen |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Eine signierte Test-Zustellung senden |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Das Signing-Secret rotieren |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | Jüngste Zustellversuche auflisten |
Geben Sie so schnell wie möglich ein 2xx zurück und verarbeiten Sie den Payload
asynchron, um Timeouts zu vermeiden:
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) }}Nutzen Sie die Aktion Test an einem Webhook (oder
POST .../webhooks/{webhookId}/test), um einen signierten Beispiel-Payload an Ihren
Endpunkt zu senden und zu bestätigen, dass er erreichbar ist und Signaturen korrekt
verifiziert.
Für die lokale Entwicklung machen Sie Ihren Server über einen Tunnel wie ngrok
erreichbar:
ngrok http 3000# Use the generated URL as your webhook endpoint