Skip to main content

Webhooks

SecureAI peut transmettre les événements de sécurité et de plate-forme à vos propres points de terminaison HTTP en temps réel : blocages de Prompt Shield, fuites Canary, incidents DLP/PII, événements de limite d’API et basculements de modèles. Chaque livraison est signée avec une signature HMAC-SHA256 afin que vous puissiez vérifier qu’elle provient de SecureAI et qu’elle n’a pas été falsifiée ou relue. Les points de terminaison Webhook sont gérés par les administrateurs dans Admin → Webhooks (base API /api/admin/webhooks).

Gestion des points de terminaison

Entrées au moment de la création : url, description, events[] (voir Events) et enabled. Le secret de signature (whsec_...) est affiché uniquement lors de la création et de la rotation — stockez-le en toute sécurité ; vous ne pouvez pas le récupérer à nouveau. Le point de terminaison url est validé par SSRF : seul http(s) est accepté et les hôtes privés/bouclage/lien-local sont rejetés à moins que l’instance ne s’exécute avec WEBHOOKS_ALLOW_PRIVATE=true (les récepteurs auto-hébergés en ont souvent besoin). ##Format de livraison Chaque livraison est un HTTP POST avec un corps JSON :
Et ces en-têtes : Votre point de terminaison doit renvoyer n’importe quel statut 2xx pour accuser réception de la livraison.

Vérification de la signature

Recalculez le HMAC sur `${t}.${rawBody}` using your signing secret and compare it to the v1 value. Reject the delivery if it doesn’t match, or if t est en dehors de votre fenêtre de tolérance (protection contre la relecture). Vérifiez par rapport au corps brut de la requête : l’analyse et la re-sérialisation du JSON en premier modifieront les octets et briseront la signature.

Node.js (Express)

Python (Flacon)

Fiabilité

  • Nouvelles tentatives : jusqu’à 3 tentatives avec un délai d’attente de 0 s/10 s/60 s, un délai d’attente de 5 s chacune. Tout 2xx reconnaît.
  • Désactivation automatique : après 20 échecs de livraison consécutifs, un point de terminaison est automatiquement désactivé ; un administrateur le réactive (ce qui réinitialise également le compteur d’échecs).
  • Au moins une fois : les livraisons peuvent se répéter — déduplication sur X-SecureAI-Delivery (ou sur la charge utile id).
  • Fire-and-forget : la livraison du webhook ne bloque ni ne retarde jamais la demande d’API d’origine.

Connexes