Webhooks

Receive real-time notifications when WardenAuth resources change. Every event is POSTed to your endpoint with an HMAC signature so you can verify it came from WardenAuth.

How it works

When a tracked event fires, WardenAuth enqueues a delivery. It makes two immediate HTTP attempts in quick succession. If both fail, a scheduled retry is set with exponential backoff — 30 seconds, then 1 minute, then 2 minutes, and so on. A cron job wakes every minute, picks up deliveries whose retry window has arrived, and re-enqueues them.

After 20 total attempts without success, the endpoint is auto-disabled and a notification is sent.

Registering an endpoint

cURL

curl -X POST https://api.wardenauthz.com/v1/scope/workspace-eng/webhooks \
  -H "x-api-key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/warden-events",
    "events": ["permission.created", "role.updated", "api-key.rotated"],
    "description": "Sync RBAC changes to audit pipeline"
  }'

Response

{
  "id": "wh-abc123",
  "url": "https://hooks.example.com/warden-events",
  "secret": "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5...",
  "events": ["permission.created", "role.updated", "api-key.rotated"],
  "active": true
}

Store secret immediately. It's shown only once and cannot be retrieved again.

Retry and failure behavior

Deliveries go through two phases:

Phase 1 — Inline retry. Each delivery job makes 2 HTTP attempts back to back (0ms, then +1s). Most transient failures resolve here.

Phase 2 — Scheduled retry. If both inline attempts fail, the delivery is scheduled for retry with exponential backoff and re-enqueued by a cron job that runs every minute (production) or every 10 minutes (dev).

The backoff sequence is:

Attempt	Delay since last attempt
1	30s
2	1m
3	2m
4	4m
5	8m
6	16m
7	32m
8	64m
9	128m
10+	4h (capped)

After 20 attempts (approx. 70 hours), the endpoint is auto-disabled. WardenAuth sends a notification to the workspace admin when this happens. No further deliveries will be attempted until the endpoint is re-enabled.

Manual retry

You can re-queue a specific failed delivery manually:

cURL

curl -X POST https://api.wardenauthz.com/v1/scope/workspace-eng/webhooks/wh-abc123/deliveries/dlv_x1y2z3/retry \
  -H "x-api-key: YOUR_MANAGEMENT_KEY"

{ "message": "Delivery re-queued for retry" }

The retry counter resets to zero, giving the delivery a full set of fresh attempts.

Verifying payloads

Every request includes an X-Webhook-Signature header. Verify it with your secret:

import crypto from 'crypto'

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

Edge cases

• api-key.rotated events never include the raw key. Your handler must call the reveal endpoint to fetch it.
• Duplicate deliveries are possible. WardenAuth guarantees at-least-once delivery. Use the X-Webhook-Idempotency-Key header to deduplicate on your side.
• An endpoint can be auto-disabled. After 20 consecutive failures, the endpoint is disabled and an admin notification fires. Re-enable it from the dashboard or API after fixing the cause of the failures.
• Response timeouts. WardenAuth waits up to 10 seconds for your endpoint to respond before treating the delivery as failed.

In the dashboard

[Screenshot: Webhooks list showing endpoints, active/disabled status, and last delivery result]

[Screenshot: Webhook detail page with delivery history, retry button on failed deliveries, and endpoint status toggle]

Navigate to Webhooks. Click New Webhook Endpoint, provide your URL, select which events to subscribe to, and WardenAuth begins delivering events immediately.