← Integration Docs

Auth webhooks

Owner/Admin → App → Webhooks. Choose an environment, add a public HTTPS receiver, and save the once-shown signing secret in your server’s secret store. Use a separate endpoint and secret for each environment. Recent authentication is required to add or disable endpoints. There are at most five active endpoints per environment.

What events mean

user.registered is the first persisted, scoped Auth session for that user (not global account creation). session.created, session.revoked, user.email_verified, user.identity_changed and user.access_changed report committed Auth-side facts. They do not prove your app completed login or verified its integration. Events have id, type, occurredAt, appId, environmentId and minimal data IDs/status; they omit passwords, tokens, email addresses and provider profiles. Unknown legacy environment sessions are not delivered. No historical backfill occurs when adding an endpoint. Payload appId is the immutable Auth database app ID, not the public client slug. Use the exact receiver scope appId/environmentId shown on the Webhooks page in signature-helper configuration.

Verify the exact raw body

Headers: Webhook-Id (event ID), Webhook-Delivery (stable delivery ID), Webhook-Timestamp (Unix seconds), Webhook-Signature (v1, followed by a base64url HMAC). Decode your signing secret as base64url; compute HMAC-SHA256 over the UTF-8 bytes of this exact concatenation:

eventId + "." + deliveryId + "." + timestamp + "." + rawBody

Use a constant-time signature comparison before parsing or acting. Reject timestamps outside a five-minute window, unknown signature versions, malformed IDs and body/header ID mismatches. Store processed event IDs in a durable unique-key table atomically with your business action, return 2xx for duplicates. Never put signing secrets in URLs, browser/mobile apps or logs. A valid signature does not authorize an action beyond the event’s app and environment.

The source SDK includes verifyWebhook in the server-only @aelith/auth-core/webhooks subpath (package publication is separate). It verifies signature, timestamp, event schema and expected app/environment, but you must still durably deduplicate event IDs. The normal browser SDK entry does not import Node crypto.

Retries and rotation

Delivery is at least once. Each retry has a fresh timestamp/signature, stable event and delivery IDs. Non-2xx, redirects, DNS/TLS failures and timeout retry up to eight attempts, starting at 30 seconds, capped at one hour between attempts. A worker crash can cause a duplicate; respond promptly and process durably. Auth does not follow redirects or retain receiver response bodies. Delivery history stores safe status codes and fixed outcomes. Maintenance removes terminal events, delivery attempts and retired endpoints after 30 days; active/queued work is retained. First-user markers remain until their environment/user is deleted. Disabling also clears the stored encrypted signing secret. Disable the old endpoint and add a new one to rotate secret or URL. Disabled endpoints cancel queued requests, but cannot recall an already-started request. Disabled environments/apps stop delivery.

Operator setup

This feature needs its additive schema migration, WEBHOOKS_ENABLED=true, WEBHOOK_DELIVERY_ENABLED=true and an operator-provided encryption keyring WEBHOOK_ENCRYPTION_KEYS_JSON with WEBHOOK_ACTIVE_KEY_ID. Keyring entries use an id and a canonical base64 32-byte encryption key. Keep older encryption keys until old endpoint secrets are retired. The platform operator configures these securely and redeploys; app developers cannot activate platform flags. No real keys are included in these docs. Keep delivery off during schema upgrades. The existing authenticated maintenance job drains a bounded batch; monitor backlog, enforce egress restrictions and provision scheduling/capacity appropriate to your traffic.

Limits and troubleshooting

Receivers must use port 443 with public DNS and valid TLS. All resolved addresses must be public; actual connections pin a validated address, preserve hostname verification, prohibit redirects and have time limits. Private networks, IP literals and reserved ranges are rejected. No request body exceeds 20 KB. NETWORK_ERROR can mean blocked DNS, timeout, TLS or unavailable encryption keys; check your public receiver without exposing secrets. HTTP_ERROR includes the response status. Off or a delivered event is not a connection-test Verified result. Production activation and real receiver verification are separate from fixture tests.