Webhooks
SecureAI kann Sicherheits- und Plattformereignisse in Echtzeit an Ihre eigenen HTTP-Endpunkte übertragen – Prompt Shield-Blöcke, Canary-Leaks, DLP/PII-Vorfälle, API-Limit-Ereignisse und Modell-Failovers. Jede Lieferung ist mit einer HMAC-SHA256-Signatur signiert, sodass Sie überprüfen können, ob sie von SecureAI stammt und nicht manipuliert oder wiederholt wurde. Webhook-Endpunkte werden von Administratoren unter Admin → Webhooks (API-Basis/api/admin/webhooks) verwaltet.
Endpunkte verwalten
Eingaben zur Erstellungszeit:
url, description, events[] (siehe Events) und enabled. Das Signaturgeheimnis (whsec_...) wird nur beim Erstellen und Rotieren angezeigt – speichern Sie es sicher; Sie können es nicht erneut abrufen.
Der Endpunkt url ist SSRF-validiert: nur http(s) wird akzeptiert und private/Loopback-/Link-Local-Hosts werden abgelehnt, es sei denn, die Instanz läuft mit WEBHOOKS_ALLOW_PRIVATE=true (selbstgehostete Empfänger benötigen dies oft).
Lieferformat
Jede Lieferung ist ein HTTPPOST mit einem JSON-Body:
Ihr Endpunkt sollte einen beliebigen
2xx-Status zurückgeben, um die Zustellung zu bestätigen.
Überprüfung der Signatur
Berechnen Sie den HMAC über „ `` using your signing secret and compare it to thev1value. Reject the delivery if it doesn't match, or ift“ liegt außerhalb Ihres Toleranzfensters (Wiedergabeschutz). Überprüfen Sie anhand des rohen Anforderungstexts – wenn Sie zuerst den JSON-Code analysieren und erneut serialisieren, werden die Bytes geändert und die Signatur beschädigt.
Node.js (Express)
Python (Flasche)
Zuverlässigkeit
- Wiederholungen: bis zu 3 Versuche mit 0s/10s/60s Backoff, jeweils 5s Timeout. Jeder
2xxbestätigt. - Automatische Deaktivierung: Nach 20 aufeinanderfolgenden Zustellungsfehlern wird ein Endpunkt automatisch deaktiviert; Ein Administrator aktiviert es erneut (wodurch auch der Fehlerzähler zurückgesetzt wird).
- Mindestens einmal: Lieferungen können wiederholt werden – deduplizieren Sie auf
X-SecureAI-Delivery(oder der Nutzlastid). - Fire-and-Forget: Die Webhook-Bereitstellung blockiert oder verzögert niemals die ursprüngliche API-Anfrage.
Verwandte
- Webhook Events – der vollständige Eventkatalog und die Payloads.
- Redundancy & Failover — Quelle von
api:model_failover. - Threat Defense – Quelle der
promptshield:*-Ereignisse.

