Webhooks overview

Webhooks push events to your server as they happen — a new user, a revoked session, an org change — so you never have to poll. Register an endpoint, subscribe it to events, and verify each delivery's signature.

Register an endpoint

The signing secret (whsec_…) is revealed exactly once at creation. Store it — you need it to verify deliveries.

const ep = await atlas.webhooks.endpoints.create({
  url: 'https://acme.com/atlas/webhooks',
  enabled_events: ['user.created', 'user.deleted', 'organization.updated'],
});
console.log(ep.secret); // whsec_… — store it now, shown once

Subscribe to "*" for all events, or list specific event names. See the full event catalog.

The delivery

Atlas POSTs a JSON payload of full resource objects (not diffs), so a consumer processing events out of order can still reconstruct state:

{
  "id": "evt_…",
  "type": "user.created",
  "timestamp": 1757600000000,
  "instance_id": "ins_…",
  "data": { "object": "user", "id": "user_2a…", "…": "…" }
}

Signature and replay-protection headers accompany every delivery — see Verifying webhooks. Respond 2xx quickly; Atlas retries failed deliveries with backoff and records each attempt in the delivery log.

Retries & retention

• Failed deliveries are retried automatically; inspect attempts via the deliveries log.

• Events are retained for 90 days; a manual redeliver after that returns 409.

• Rotating the secret takes effect immediately — deliveries signed with the old secret are rejected.