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.Setup
Pass an array of endpoints aswebhooks to createTheAuth. Each endpoint has its own URL, secret, and event list. The instance then exposes theauth.webhooks (null when no endpoints were configured).
Endpoint options
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.Event types this endpoint receives. There is no
'*' wildcard: list every event you want.theauth.webhooks?.addEndpoint({ ... }) and read them back with listEndpoints().
Event reference
These are the event names accepted byemit 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.- Node
- Edge (Web Crypto)
Rotating the signing secret
Each delivery is signed with one key, the first entry ofsecret. 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.
- 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. - 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. - After the retry window and your timestamp tolerance have passed, remove the old key from the receivers and the sender:
secret: [newSecret].
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.
_ 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 toretries 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.