Skip to main content

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 HTTP POST with a JSON body:
And these headers: 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 2xx acknowledges.
  • 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 payload id).
  • Fire-and-forget: webhook delivery never blocks or delays the originating API request.