Quickstart

Create a subscription in the Atlas dashboard under Settings, then Webhooks, or call the API directly. Both take the same two required fields: url (a public HTTPS endpoint, max 2048 characters) and events (1 to 50 event patterns to subscribe to).

curl -X POST https://api.example.com/v1/webhooks \
  -H "Authorization: Bearer atlas_pat_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/atlas/webhook","events":["task.completed","project.*"]}'

The response returns { webhook, secret }. The webhook object holds the subscription details; secret is the signing key you use to verify every future payload.

Stand up an endpoint that returns a 2xx response quickly. Atlas times out a delivery after 10 seconds, so acknowledge fast and push any heavy work onto an asynchronous queue rather than doing it inline.

app.post(
  "/atlas/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // verify first (see Security), then enqueue and respond fast
    res.status(200).send("ok");
  },
);

You MUST verify the signature before trusting a payload. Recompute an HMAC-SHA256 over `${timestamp}.${webhookId}.${body}` keyed by your signing secret, then compare it against the x-atlas-webhook-signature header. See Security and signing for full verification code in five languages.

Send a test delivery from the dashboard, or call POST /v1/webhooks/{id}/test-delivery, which emits a webhook.test event. Watch it land in delivery history, confirm your endpoint verified and acknowledged it, then start relying on real events. See Delivery and retries and Events for what happens next.