Webhooks
SecureAI can push security and platform events to your own HTTP endpoints in real time — Prompt Shield blocks, canary leaks, DLP/PII incidents, API limit events, and model failovers. Every delivery is signed with an HMAC-SHA256 signature so you can verify it came from SecureAI and was not tampered with or replayed. Webhook endpoints are managed by administrators in Admin → Webhooks (API base/api/admin/webhooks).
Managing endpoints
Create-time inputs:
url, description, events[] (see Events), and enabled. The signing secret (whsec_...) is shown only on create and rotate — store it securely; you cannot retrieve it again.
The endpoint url is SSRF-validated: only http(s) is accepted, and private/loopback/link-local hosts are rejected unless the instance runs with WEBHOOKS_ALLOW_PRIVATE=true (self-hosted receivers often need this).
Delivery format
Each delivery is an HTTPPOST with a JSON body:
Your endpoint should return any
2xx status to acknowledge the delivery.
Verifying the signature
Recompute the HMAC over`${t}.${rawBody}` using your signing secret and compare it to the v1 value. Reject the delivery if it doesn’t match, or if t is outside your tolerance window (replay protection). Verify against the raw request body — parsing and re-serializing the JSON first will change the bytes and break the signature.
Node.js (Express)
Python (Flask)
Reliability
- Retries: up to 3 attempts with 0s / 10s / 60s backoff, 5s timeout each. Any
2xxacknowledges. - Auto-disable: after 20 consecutive delivery failures an endpoint is automatically disabled; an admin re-enables it (which also resets the failure counter).
- At-least-once: deliveries may repeat — deduplicate on
X-SecureAI-Delivery(or the payloadid). - Fire-and-forget: webhook delivery never blocks or delays the originating API request.
Related
- Webhook Events — the full event catalog and payloads.
- Redundancy & Failover — source of
api:model_failover. - Threat Defense — source of the
promptshield:*events.

