Skip to main content

What webhooks do

Webhooks push signed HTTP POST requests to a URL you control. Use them to sync user records, trigger onboarding flows, alert on suspicious logins, or feed events into your analytics pipeline.
Webhooks are a delivery mechanism, not an event source. The theAuth core does not call emit for you when a user signs up or an agent is created. Your code (or a lifecycle hook) calls theauth.webhooks?.emit(event, payload) at the points where you want a delivery to happen.

Setup

Pass an array of endpoints as webhooks to createTheAuth. Each endpoint has its own URL, secret, and event list. The instance then exposes theauth.webhooks (null when no endpoints were configured).
Store the webhook secret in an environment variable, not in source code. theAuth uses it to sign every request with HMAC-SHA256.

Endpoint options

string
Destination URL for the POST request.
string | Array<string | { id: string; secret: string }>
Signing secret used for the HMAC-SHA256 signature. Pass an array, [current, ...previous], to rotate: the first entry signs. Array entries must be at least 32 bytes, empty and duplicate entries are rejected when webhooks() is created. A plain string keeps working as before.
WebhookEvent[]
Event types this endpoint receives. There is no '*' wildcard: list every event you want.
number
Retry attempts after the first failed delivery. Defaults to 3.
number
Per-request timeout in milliseconds. Defaults to 10000.
You can add endpoints at runtime with theauth.webhooks?.addEndpoint({ ... }) and read them back with listEndpoints().

Event reference

These are the event names accepted by emit and by an endpoint’s events list: The meaning column describes what you would emit the event for. The library does not emit these automatically. Delegation and approval events are not part of this list.

Payload

The request body is JSON:
timestamp is Unix time in seconds, as a string, and data is the payload you passed to emit.

Request headers

Every webhook delivery includes these headers:

Verifying signatures

The signature covers the timestamp and the raw body joined by a dot, not the body alone. Always verify it before trusting the payload, and reject old timestamps to limit replays.

Rotating the signing secret

Each delivery is signed with one key, the first entry of secret. Receivers rotate by accepting both keys for a while. Add the new key first, deploy, then remove the old one, so no delivery is ever rejected.
  1. Generate a new secret (openssl rand -base64 32) and add it to the receivers: secret: [oldSecret, newSecret]. Deploy the receivers. Nothing changes yet, because the sender still signs with the old key.
  2. Switch the sender to sign with the new key and keep the old one: secret: [newSecret, oldSecret]. Deploy. Deliveries now carry the new signature, and in-flight retries signed earlier still verify.
  3. After the retry window and your timestamp tolerance have passed, remove the old key from the receivers and the sender: secret: [newSecret].
The verify helper from @glinr/theauth/webhook accepts the same list. It checks every key and does not stop at the first match, so timing does not reveal which key signed.
Key ids (letters, digits, _ and -, up to 32 characters) are optional labels. They only choose which key is tried first. The secrets are never logged or included in error messages.

Retry behavior

If your endpoint returns a non-2xx status, errors, or times out, theAuth retries up to retries times (default 3) after the first attempt, with exponential backoff: After the last retry the delivery is dropped silently. There is no persisted delivery record, no failed state, and no replay: retries run in memory in the same process, so a restart loses pending retries.

Standalone subscription module

@glinr/theauth also exports a separate createWebhookModule({ secret, maxRetries?, timeoutMs? }) with runtime subscriptions kept in memory: subscribe(url, events), unsubscribe(id), list(), dispatch(event, payload), and test(subscriptionId). It is independent of theauth.webhooks, signs the raw body only (X-TheAuth-Signature: sha256=<hex> of the body, plus X-TheAuth-Delivery and an ISO X-TheAuth-Timestamp), tries up to maxRetries attempts in total, and accepts a different event list that includes delegation.created, delegation.revoked, auth.login, auth.logout, auth.failed, and org.* events. Verify its deliveries with the exported verifyWebhookSignature(secret, rawBody, signature). Subscriptions are lost on restart.

Next steps

Lifecycle hooks

Run async callbacks on auth events inside the SDK process.

Audit log

Query the full record of every authorization decision.
Last modified on October 18, 2026