Webhooks

Webhooks push audit log events to systems outside the gateway the moment they happen — a SIEM or an internal service. Each webhook subscribes to a set of event types; matching events are delivered as HTTP requests to your endpoint, with a per-delivery attempt log so you can see exactly what was sent and how the receiver responded. Custom headers let one webhook target most receivers without a vendor-specific integration.

Each webhook's page lists recent deliveries with the full attempt timeline — status codes, latency, and a truncated response snippet. Delivery history is retained for 30 days.

Retries and the circuit breaker

Failed deliveries are retried automatically over roughly a day, so a brief receiver outage recovers on its own. A rate-limited endpoint (429) is backed off more gently and isn't treated as failing. An endpoint that's gone (410), or that keeps failing for three days, is disabled automatically and records a webhook.disabled audit event so you're notified. Re-enable a disabled webhook from its page — this clears its failure history — or re-run a single failed delivery.

Create a webhook

1. Go to Webhooks in the sidebar and click New webhook.
2. Set a name and the endpoint URL.
3. Choose the events to subscribe to — leave All events on, or pick specific actions such as gateway.tool.error or policy.created. The list mirrors the auditable actions in the audit log.
4. Optionally add custom headers (sent with every request; values are stored encrypted).
5. Click Create webhook.

Request format

Every delivery is an HTTP POST:

POST /hooks/audit HTTP/1.1
content-type: application/json
user-agent: secureauth-ai-gateway/1.0

Your custom headers are appended after the reserved ones; reserved names can't be overridden.

Any 2xx response marks the delivery as succeeded. Redirects are not followed.

Payload reference

Each delivery carries a single JSON body per event, wrapped in a Standard Webhooks envelope; data carries the audit event exactly as the audit log stores it:

{
  "type": "tag.created",
  "timestamp": "2026-07-06T12:34:56.789Z",
  "data": {
    "id": "01981c2f-3a4b-7c5d-8e6f-0a1b2c3d4e5f",
    "org_id": "0197f6f4-9d2e-7a3b-b4c5-d6e7f8a9b0c1",
    "action": "tag.created",
    "actor_type": "user",
    "actor_id": "d7a2e4b1-3c9f-4d6e-a518-7f0b2c8e9d34",
    "actor_display_name": "John Doe",
    "resource_type": "tag",
    "resource_id": "b1c2d3e4-0a1b-4c2d-8e3f-1a2b3c4d5e61",
    "resource_display_name": "pii",
    "resources": {
      "tag_id": "b1c2d3e4-0a1b-4c2d-8e3f-1a2b3c4d5e61",
      "tag_display_name": "pii"
    },
    "context": {
      "ip": "203.0.113.7",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "trace_id": "6f2c1a0d9b8e7f6a5c4d3b2a1e0f9d8c"
    },
    "changes": [],
    "payload": {
      "tag_id": "b1c2d3e4-0a1b-4c2d-8e3f-1a2b3c4d5e61",
      "name": "pii",
      "namespace": "resource",
      "color": "red"
    },
    "created_at": "2026-07-06T12:34:56.789Z"
  }
}