Brauche ich Webhooks, wenn ich schon die Data API nutze?

Nein, aber die meisten Teams betreiben beides. Die Data API antwortet über den Besuch, den Sie gerade ansehen; Webhooks erzählen Ihnen von den Besuchen, die Sie nicht ansehen — ein Bot-Angriff um 3 Uhr nachts, eine Kontoübernahme in einer Sitzung, die niemand beobachtet. Webhooks tragen außerdem spätere Phasen: Ein Verdict, das durch langsamere Hinweise korrigiert wurde, kommt als neue Zustellung.

Was passiert, wenn mein Endpunkt ausfällt?

Wir wiederholen auf einer sich weitenden Leiter — 5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h — acht Versuche, verteilt über rund 4,4 bis 8,7 Stunden, jede Pause zufällig gestreut, damit die Wiederholungen nicht als eine Salve ankommen. Ein Neustart, der eine Minute dauert, kostet Sie nichts, und ein Webhook wird erst nach einer Fehlerserie abgeschaltet, die sowohl die Schwelle erreicht als auch mindestens 15 Minuten am Stück anhält.

Muss ich beide Signaturen prüfen?

Für die meisten Integrationen genügt die Prüfung des HMAC; sie funktioniert bei beiden Payload-Schemata. Die Ed25519-Plattform-Signatur ist die stärkere Option — ein öffentlicher Schlüssel statt eines geteilten Secrets — und kommt mit Schema 2. Wenn Ihre Prüfroutine sie verlangt, lassen Sie Testzustellungen aus dem Dashboard trotzdem durch: Sie tragen konstruktionsbedingt nur den HMAC, weil der private Plattformschlüssel die Zustellknoten nie verlässt.

Können die Data API und ein Webhook über denselben Besuch uneins sein?

Sie können sich unterscheiden, und das ist kein Widerspruch. Die Data API antwortet aus dem primären Datensatz — dem Stand beim Laden der Seite. Spätere Phasen erreichen Sie als Webhook-Zustellungen und werden nicht in ihn zurückgeschrieben. Sie beantworten verschiedene Fragen: was wir in jenem Moment wussten, gegenüber dem, was wir geschlossen haben, während weitere Hinweise eintrafen. Wenn Sie Minuten nach dem Besuch handeln, vertrauen Sie der Phase, die Sie zuletzt erhalten haben.

Welchen Tarif brauche ich?

Webhooks beginnen bei Pro — fünf pro Workspace, 20 bei Business, 100 bei Enterprise. Die Data API gibt es ab Pro. Guidance, Reason-Codes zum Verdict, Verhaltenssignale und browserübergreifende Gerätedaten gibt es ab Business.

Datenauslieferung

Ihre Daten — dort, wo Sie entscheiden

Jede Identifikation kann Ihre Systeme auf zwei Wegen erreichen: gepusht an Ihren Server in dem Moment, in dem sie passiert, oder von Ihnen abgeholt in genau der Sekunde, in der Sie entscheiden. Beide Kanäle tragen dieselben Zahlen — festgehalten wird das von einem Test, nicht von einem Versprechen.

Kostenlos testen Demo buchen

Zwei Kanäle

Push oder Pull

Webhooks schieben Events zu Ihnen, sobald sie passieren. Mit der Data API fragen Sie in dem Moment, in dem Sie eine Antwort brauchen. Die meisten Teams betreiben beides: Webhooks zum Protokollieren und Reagieren, die Data API für die Prüfung im laufenden Ablauf.

Webhooks — Push, in Echtzeit

Wir POSTen ein signiertes JSON-Event an Ihren Endpunkt, sobald etwas passiert: Ein Besucher wird identifiziert, eine Kontoübernahme wird markiert, ein Bot-Angriff beginnt. Nichts zu pollen, nichts zu planen.

Am besten für: jeden Besuch protokollieren, auf Angriffe reagieren, Ihr Warehouse oder SIEM speisen.

p50-Zustelllatenz 44–140 ms, vom Event bis zu Ihrem Endpunkt.

Data API — Pull, auf Abruf

Eine private Server-zu-Server-API. Ihr Backend authentifiziert sich mit einem geheimen Schlüssel und liest genau das, was wir über einen Besucher wissen, in der Sekunde seiner Entscheidung — typischerweise im Handler für Login oder Checkout.

Am besten für: eine Prüfung im Ablauf, bevor Sie eine Karte belasten, eine Anmeldung freigeben oder ein Konto entsperren.

Ab dem Pro-Tarif verfügbar.

Webhooks

Vier Event-Typen, ein Umschlag

Jede Zustellung kommt im selben Umschlag, mit dem Event-Typ im Body und im Header X-Tracio-Event-Type — ein einziger Handler kann also alle vier verteilen.

Besucher identifiziert

Das Kernereignis: Ein Besuch wurde bewertet. Es trägt die Besucher-ID, Browser und Betriebssystem, Geo und Netzwerk, das Bot-Verdict und die Risikoentscheidung. Ausgeliefert wird in Phasen — ein primäres Event beim Laden der Seite, dann eine späte Phase oder eine Korrekturphase, wenn langsamere Hinweise das Verdict ändern. Phasen korrelieren Sie über requestId.

identification

Kontoübernahme

Der Detektor für Kontoübernahme hat bei einem Besuch ausgelöst: Das Gerät hinter einem bekannten Konto sieht nicht mehr aus wie das Gerät, dem es gehört. Es kommt als eigenes Event mit dem Kontokontext im Anhang, statt sich in einem Identifikations-Body zu verstecken.

account_takeover

Bot-Angriff

Ein Anstieg automatisierten Traffics in Ihrem Workspace. Hinter diesem Event steht kein Besuch — es ist eine Warnung auf Workspace-Ebene, deshalb fehlen die Besuchsblöcke im Body schlicht, statt als leere Hüllen mit auf null gesetzten Scores anzukommen.

attack_detected

Reputationsänderung

Ein Profil hat das Reputationsband gewechselt. Derselbe Umschlag wie bei der Angriffswarnung — ein Event auf Profilebene ohne angehängten Besuch, das das neue und das vorherige Band trägt.

reputation_changed

Eine Zustellung, gekürzt

Das ist der Basis-Body. Pro ergänzt die Besuchsfrequenz; Business ergänzt Reason-Codes zum Verdict, Verhaltenssignale, Guidance und browserübergreifende Gerätedaten — in genau derselben Form: Es kommen neue Blöcke hinzu, bestehende Pfade verschieben sich nie.

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

Jede Anfrage trägt zwei Signaturen

X-Tracio-Signature ist ein HMAC-SHA256 über den Signatur-Zeitstempel, verbunden mit dem rohen Request-Body und mit Ihrem Webhook-Secret als Schlüssel — er belegt, dass der Absender das Secret kennt, das Sie beide halten. X-Tracio-Signature-Ed25519 ist die Plattform-Signatur: Sie prüfen sie mit einem öffentlichen Schlüssel, den Sie von einem Well-known-Endpunkt holen — auf Ihrer Seite muss also nichts Geheimes gespeichert werden. Der Zeitstempel ist Teil des signierten Inhalts, und genau das macht einen alten Mitschnitt für ein Replay wertlos.

Prüfen Sie gegen die rohen Request-Bytes — neu serialisiertes JSON verändert die Bytes, und die Signatur passt dann nicht mehr. Wiederholungen tragen dieselbe X-Tracio-Event-Id; deduplizieren Sie darüber.

Header bei jeder Zustellung

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

Zuverlässigkeit

Gebaut, um keine Events zu verlieren

Die Zustellung läuft auf einer eigenen Flotte, und die Quelle der Wahrheit ist die Queue — nicht der Speicher eines Prozesses. Genau das macht At-least-once echt: Stirbt ein Zustellknoten mitten im Flug, liegt das Event weiterhin in der Queue und ein anderer Knoten nimmt es auf.

Events pro Sekunde durch einen einzelnen Webhook — vor dem Umbau im Juli waren es rund 50

44–140 msp50-Zustelllatenz vom Event bis zu Ihrem Endpunkt

Zustellversuche auf einer sich weitenden Leiter, verteilt über bis zu 8,7 Stunden

von 90.000 Events in einem Test zugestellt, bei dem ein Zustellknoten unter Last abgeschaltet wurde

Wiederholungen, die zu echten Ausfällen passen

5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. Die ersten Wiederholungen landen innerhalb einer Minute, ein kurzer Neustart Ihres Dienstes kostet Sie also nichts. Jede Pause wird zufällig zwischen der Hälfte des genannten Werts und dem vollen Wert gewählt, damit Wiederholungen nach einem Ausfall nicht als eine einzige Salve zurückkommen.

Automatische Abschaltung, die nicht danebengreift

Ein Webhook wird erst abgeschaltet, wenn die Fehler sowohl die Schwelle erreichen als auch mindestens 15 Minuten am Stück andauern — ein Schwall aufgestauter Zustellungen während eines Neustarts beendet die Integration also nicht. Ein 410 Gone schaltet sofort ab. Das Dashboard zeigt den Grund, den Antwortcode und eine Schaltfläche zum Wiedereinschalten.

Secret-Rotation ohne Lücke

Nach einer Rotation bleiben beide Secrets 24 Stunden gültig, und der Header trägt beide Signaturen — eine Übereinstimmung mit einer von beiden genügt. Sie aktualisieren Ihre Konfiguration innerhalb dieses Fensters, statt gegen einen Stichtag zu rennen; „Jetzt widerrufen“ verkürzt das Fenster, wenn es sofort weg sein muss.

Ein Zustellprotokoll, das man lesen kann

Jeder Versuch — Antwortcode, Dauer, Fehlertext — ist pro Webhook im Dashboard sichtbar, direkt neben einer Testaktion, die eine signierte Beispiel-Payload an Ihren Endpunkt schickt, damit Sie Ihre Prüfroutine bestätigen können, bevor Sie live gehen.

Data API

Fragen in dem Moment, in dem Sie entscheiden

Eine private Server-zu-Server-API auf api.tracio.ai. Ihr Backend authentifiziert sich mit einem geheimen Schlüssel und liest seine eigenen Daten. Sie sendet bewusst keine CORS-Header: Ein geheimer Schlüssel gewährt Zugriff auf alles in Ihrem Workspace und darf niemals in einen Browser gelangen. Ab dem Pro-Tarif verfügbar.

Methode	Pfad	Liefert
GET	/v1/visitors/{visitorId}	Besucherzusammenfassung: zuerst und zuletzt gesehen, Anzahl der Besuche, eindeutige IPs und Länder, Browser und Geräte, Risikohistorie — dazu die jüngste Sitzung.
GET	/v1/visitors/{visitorId}/sessions	Sitzungsliste mit Cursor-Paginierung und Filtern nach Zeitraum, Bot-Ergebnis und minimalem Risiko-Score.
GET	/v1/visitors/{visitorId}/sessions/latest	Die jüngste Sitzung als einzelnes Objekt, ohne Listen-Hülle.
GET	/v1/sessions/{requestId}	Eine bestimmte Sitzung. Geben Sie visitorId dazu, dann läuft die Suche über den Besucherindex statt über Ihre gesamte Historie.
GET	/v1/visitors/{visitorId}/velocity	Aktivität über ein Fenster — 1 h, 24 h oder 7 d: wie viele Besuche, von wie vielen IPs, aus wie vielen Ländern, unter wie vielen Konten.

Einen Besucher an der Kasse prüfen

Der typische Aufruf: in Ihrem Zahlungs-Handler, bevor Sie die Karte autorisieren. Eine Anfrage, eine Antwort, und der meta-Block meldet das Fenster, das Sie tatsächlich bekommen haben — fragen Sie sechs Monate ab und Ihr Tarif hält 30 Tage vor, liefert er 30 Tage und sagt es dazu.

Anfrage

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"

Antwort

JSON

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

Überall dieselben Zahlen

Ein Besuch, der in Ihrem Dashboard 65,9 erreicht, erreicht 65,9 in der Data API und 65,9 im Webhook-Body. Zwei unabhängige Darstellungen könnten auseinanderdriften — Skalen sind der klassische Fall, wenn ein Kanal Ihnen 0,93 gibt, wo der andere 93 sagt —, deshalb baut ein Paritätstest einen einzelnen Besuch, rendert ihn durch beide Kanäle und vergleicht die öffentlichen Felder auf rohem JSON. Die Übereinstimmung wird erzwungen, nicht behauptet.

Guidance — ab Business

Empfehlungen, nicht nur Zahlen

Scores sagen Ihnen, was wir gesehen haben. Guidance sagt Ihnen, was daraus folgt — für die vier Entscheidungen, die tatsächlich Geld kosten, berechnet aus versionierten Regeln und mit der Begründung im Gepäck.

Zahlung annehmen?

Gewichtet Risiko, Betrugsreputation und das Bot-Verdict, bevor Sie eine Karte autorisieren.

Anmeldung akzeptieren?

Fängt das Wegwerfkonto ab, bevor es existiert — Multi-Accounting und Reputation wiegen hier am schwersten.

Einlassen?

Zieht automatisch an, wenn der Detektor für Kontoübernahme bei diesem Besuch ausgelöst hat.

Conversion zählen?

Trennt eine echte Empfehlung von einer Selbstempfehlung oder einem incentivierten Bot.

Ein Vokabular aus vier Wörtern

allowNichts, worauf zu reagieren wäre.

challengeEinen zweiten Faktor verlangen.

reviewFür einen Menschen zurückhalten.

denyRundheraus ablehnen.

Jedes Szenario bekommt eine von vier Antworten und dazu die Grundlage, auf der sie ergangen ist — die ausschlaggebenden Achsen aus einem festen Vokabular: Bot, Risiko, Betrugsreputation, Verhalten, Multi-Accounting, Kontoübernahme, Netzwerk, Affiliate-Muster. Sie wissen immer, welche Achse die Empfehlung bewegt hat, ohne je Signalnamen, Gewichte oder Schwellen zu sehen.

Eine Berechnung, drei Kanäle

Derselbe Guidance-Block reist im Webhook mit, antwortet in der Data API und wird auf der Besucherkarte im Dashboard dargestellt — ein Regelsatz, ein Ergebnis, kein Abgleich auf Ihrer Seite. Lesen Sie die Empfehlung zu Ihrem Szenario und nicht overall: overall ist schlicht die strengste der vier, eine Zusammenfassung für Dashboards und keine Zahlungsentscheidung. Die Regelversion reist in der Payload mit — eine Regeländerung bemerken Sie also, statt sie aus verschobenen Empfehlungen zu erschließen.

JSON

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

Integration

Fünf SDKs im Frontend, zwei Kanäle im Backend

Die Browser-Seite kommt als fünf SDKs — Vanilla JavaScript, React, Vue 3, Angular und Svelte 5. Serverseitige SDKs gibt es nicht, und das ist Absicht: Ihr Backend bindet sich über einfaches HTTP an, über signierte Webhooks und die Data API. Die Signaturprüfung sind ein Dutzend Zeilen gegen einen Referenzvektor, den wir veröffentlichen — und in Ihrem Server-Abhängigkeitsbaum muss nichts zusätzlich aktuell gehalten werden.

Browser-SDKs

JavaScriptReactVue 3AngularSvelte 5

SDKs ansehen API-Referenz Webhook-Doku

FAQ

Häufig gestellte Fragen

An einem Nachmittag angebunden

Legen Sie im Dashboard einen Webhook an, richten Sie ihn auf Ihren Endpunkt und drücken Sie auf Test. Prüfen Sie die Signatur gegen unseren Referenzvektor — damit ist der schwierige Teil hinter Ihnen.

Kostenlos testen Demo buchen