Quickstart

Create a subscription in the Atlas dashboard under Settings, then Webhooks, or call the API directly. Both create the same webhook, from two required fields: url (a public HTTPS endpoint of at most 2,048 characters) and events (1 to 50 event names, each an exact name, a wildcard such as project.*, or *).

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 webhook details; secret, which starts with whsec_, is the signing key you use to verify every delivery.

Stand up an endpoint that returns a 2xx response quickly. Atlas waits 15 seconds for an answer, so acknowledge at once and move any heavy work onto a queue of your own 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");
  },
);

Verify the signature before you trust a payload. The Atlas-Signature header reads t=<seconds>,v1=<hex>: compute the HMAC-SHA256 of `${t}.${rawBody}` with your signing secret, compare it with each v1, and refuse a t more than five minutes from your clock. See Security and signing for verification code in five languages.

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