Skip to main content

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 HTTP POST mit einem JSON-Body:
Und diese Überschriften: Ihr Endpunkt sollte einen beliebigen 2xx-Status zurückgeben, um die Zustellung zu bestätigen.

Überprüfung der Signatur

Berechnen Sie den HMAC über „ tneu.{t} neu. `` 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 2xx bestä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 Nutzlast id).
  • Fire-and-Forget: Die Webhook-Bereitstellung blockiert oder verzögert niemals die ursprüngliche API-Anfrage.

Verwandte