Funktionsweise
1
Einen Endpunkt registrieren
Fügen Sie einen Webhook-Endpunkt unter Einstellungen > Webhooks in der Mandantenkonsole hinzu. Geben Sie eine öffentlich erreichbare HTTPS-URL an und wählen Sie aus, welche Ereignistypen Sie empfangen möchten.
2
Ereignisse empfangen
Wenn ein passendes Ereignis eintritt, sendet Truthlocks eine HTTP POST-Anfrage an Ihre URL mit einer JSON-Nutzlast, die das Ereignis beschreibt.
3
Signatur verifizieren
Jede Anfrage enthält eine HMAC-SHA256-Signatur im
X-Truthlocks-Signature-Header. Verifizieren Sie diese mit dem Endpunkt-Geheimnis, um zu bestätigen, dass die Anfrage von Truthlocks stammt.4
Mit 200 antworten
Geben Sie einen HTTP-
200 Statuscode zurück, um den Empfang zu bestätigen. Wenn Ihr Endpunkt fehlschlägt oder eine Zeitüberschreitung auftritt, versucht Truthlocks es mit exponentiellem Backoff erneut.Ereignistypen
Ereignisse werden in Kategorien gruppiert. Sie können einzelne Ereignisse abonnieren oder einen Platzhalter (attestation.*) verwenden, um alle Ereignisse in einer Kategorie zu erhalten.
Wildcard-Filter
Verwenden Siecategory.*, um jedes Ereignis in einer Kategorie zu abonnieren. Zum Beispiel entspricht attestation.* den Werten attestation.created, attestation.revoked, attestation.expired und attestation.superseded.
Endpunktlimits nach Plan
Die Anzahl der Webhook-Endpunkte, die Sie erstellen können, hängt von Ihrer Planstufe ab:
Benötigen Sie weitere Endpunkte? Kontaktieren Sie Ihren Account Manager oder aktualisieren Sie Ihren Plan unter Einstellungen > Abrechnung.
Einen Endpunkt erstellen
- Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks.
- Klicken Sie auf Endpunkt hinzufügen.
- Geben Sie einen Namen, Ihre HTTPS-Ziel-URL ein und wählen Sie die Ereignistypen aus, die Sie empfangen möchten.
- Klicken Sie auf Erstellen.
Über die API
Request
Response
Endpunkte auflisten
Rufen Sie alle Webhook-Endpunkte für Ihren Mandanten ab:Request
Signaturen verifizieren
Jede Webhook-Anfrage enthält einen Signatur-Header zur Verifizierung. Verifizieren Sie Signaturen immer, bevor Sie Ereignisse verarbeiten. Signaturformat:t der Unix-Zeitstempel und v1 der HMAC-SHA256-Hex-Digest ist.
Verifizierungsschritte:
- Extrahieren Sie
t(Zeitstempel) undv1(Signatur) aus dem Header. - Lehnt die Anfrage ab, wenn der Zeitstempel älter als 5 Minuten ist.
- Verketten Sie
{timestamp}.{raw_request_body}, um den Signaturstring zu bilden. - Berechnen Sie HMAC-SHA256 des Signaturstrings mit Ihrem Endpunkt-Geheimnis.
- Vergleichen Sie den berechneten Digest mit
v1unter Verwendung eines Vergleichs mit konstanter Zeit.
Anfrage-Header
Jede Webhook-Zustellung enthält diese Header:Wiederholungsverhalten
Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder nicht innerhalb von 5 Sekunden antwortet, versucht Truthlocks die Zustellung mit exponentiellem Backoff erneut:
Verzögerungen beinhalten bis zu 30 % Jitter. Nach insgesamt 8 Versuchen (1 initialer + 7 Wiederholungen) wird die Zustellung als fehlgeschlagen markiert.
Sie können Zustellversuche und Fehlerdetails unter Einstellungen > Webhooks anzeigen, indem Sie auf einen Endpunkt klicken, oder sie über die API abfragen:
Request
Rotierende Geheimnisse
Wenn Ihr Webhook-Geheimnis kompromittiert ist, rotieren Sie es sofort:- Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks und klicken Sie auf den Endpunkt.
- Klicken Sie auf Geheimnis rotieren.
- Kopieren Sie das neue Geheimnis – das alte Geheimnis funktioniert sofort nicht mehr.
Request
Webhooks testen
Senden Sie ein Testereignis, um zu überprüfen, ob Ihr Endpunkt funktioniert:- Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks und klicken Sie auf den Endpunkt.
- Klicken Sie auf Test senden.
- Ein
webhook.test-Ereignis wird über die vollständige Signatur- und Zustellpipeline an Ihre URL gesendet.
Request
event_type und payload sind optional – sie verwenden standardmäßig webhook.test und eine grundlegende Status-Payload, wenn sie weggelassen werden.
Benachrichtigungen über Risikosignale
Sie können Echtzeit-Webhook-Benachrichtigungen erhalten, wann immer ein Risikosignal von einem der fünf Anti-Fraud Identity Firewall Erkennungspfade erstellt wird – direkte Aufnahme, Ereignisnormalisierung, Deepfake-Scanning, ATO-Erkennung und Geschwindigkeitsbewertung. Abonnieren Sierisk.signal.*, um alle Risikosignalereignisse zu erhalten, oder abonnieren Sie risk.signal.created oder risk.signal.escalated einzeln.
Beispiel-Payload
Reaktion auf Risikosignale
Verwenden Sie Risikosignal-Webhooks, um automatisierte Antworten auszulösen – eine Benutzersitzung blockieren, Ihr Sicherheitsteam benachrichtigen oder einen Betrugsfall eskalieren – ohne die API abzufragen.Risikosignal-Webhooks werden für Signale ausgelöst, die von allen fünf Erkennungspfaden erstellt wurden. Das Feld
signal_source in der Nutzlast gibt an, welcher Pfad das Signal generiert hat – external, event_normalization, deepfake, ato oder velocity.Best Practices
- Jede Signatur verifizieren. Überspringen Sie niemals die Signaturverifizierung, auch nicht in der Entwicklung.
- Verwenden Sie eine Nachrichtenwarteschlange. Reihen Sie eingehende Ereignisse ein und verarbeiten Sie sie in einem Worker, um das Blockieren der HTTP-Antwort zu vermeiden.
- Duplikate behandeln. Verwenden Sie den
X-Truthlocks-Event-IdHeader, um Ereignisse bei Wiederholungsversuchen zu deduplizieren. - Lieferfehler überwachen. Überprüfen Sie regelmäßig den Tab „Lieferungen“ in der Konsole auf fehlgeschlagene oder tote Lieferungen.
- Geheimnisse sicher aufbewahren. Speichern Sie Ihr Webhook-Geheimnis in Umgebungsvariablen, nicht im Quellcode.

