Zum Hauptinhalt springen
Webhooks ermöglichen Ihrer Anwendung, automatische Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrem Truthlocks-Konto auftreten – zum Beispiel, wenn eine Bestätigung geprägt wird, ein Schlüssel rotiert wird oder eine Verifizierung fehlschlägt. Anstatt die API auf Änderungen abzufragen, empfängt Ihr Server eine HTTP-POST-Anfrage mit den Ereignisdetails.

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 Sie category.*, 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

  1. Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks.
  2. Klicken Sie auf Endpunkt hinzufügen.
  3. Geben Sie einen Namen, Ihre HTTPS-Ziel-URL ein und wählen Sie die Ereignistypen aus, die Sie empfangen möchten.
  4. Klicken Sie auf Erstellen.
Die Konsole zeigt Ihr Endpunkt-Geheimnis einmal an. Kopieren Sie es sofort – Sie können es später nicht mehr abrufen.

Über die API

Request
Response

Endpunkte auflisten

Rufen Sie alle Webhook-Endpunkte für Ihren Mandanten ab:
Request
Die vollständige API-Referenz für Details zur Antwort finden Sie hier.

Signaturen verifizieren

Jede Webhook-Anfrage enthält einen Signatur-Header zur Verifizierung. Verifizieren Sie Signaturen immer, bevor Sie Ereignisse verarbeiten. Signaturformat:
Wobei t der Unix-Zeitstempel und v1 der HMAC-SHA256-Hex-Digest ist. Verifizierungsschritte:
  1. Extrahieren Sie t (Zeitstempel) und v1 (Signatur) aus dem Header.
  2. Lehnt die Anfrage ab, wenn der Zeitstempel älter als 5 Minuten ist.
  3. Verketten Sie {timestamp}.{raw_request_body}, um den Signaturstring zu bilden.
  4. Berechnen Sie HMAC-SHA256 des Signaturstrings mit Ihrem Endpunkt-Geheimnis.
  5. Vergleichen Sie den berechneten Digest mit v1 unter Verwendung eines Vergleichs mit konstanter Zeit.
Verwenden Sie immer eine Vergleichsfunktion mit konstanter Zeit (wie crypto.timingSafeEqual oder hmac.compare_digest), um Timing-Angriffe zu verhindern.

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
Details zur Antwort finden Sie in der API-Referenz für Lieferungen auflisten.

Rotierende Geheimnisse

Wenn Ihr Webhook-Geheimnis kompromittiert ist, rotieren Sie es sofort:
  1. Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks und klicken Sie auf den Endpunkt.
  2. Klicken Sie auf Geheimnis rotieren.
  3. Kopieren Sie das neue Geheimnis – das alte Geheimnis funktioniert sofort nicht mehr.
Sie können auch über die API rotieren:
Request

Webhooks testen

Senden Sie ein Testereignis, um zu überprüfen, ob Ihr Endpunkt funktioniert:
  1. Gehen Sie in der Mandantenkonsole zu Einstellungen > Webhooks und klicken Sie auf den Endpunkt.
  2. Klicken Sie auf Test senden.
  3. Ein webhook.test-Ereignis wird über die vollständige Signatur- und Zustellpipeline an Ihre URL gesendet.
Über die API:
Request
Die Felder 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 Sie risk.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

Reagieren Sie schnell auf Webhooks. Führen Sie Ihre aufwendige Verarbeitung asynchron durch, nachdem Sie eine 200-Antwort zurückgegeben haben, um Timeouts und Wiederholungsversuche zu vermeiden.
  • 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-Id Header, 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.