Webhooks

Get notified when todos or boards change. Each webhook can cover your whole account or only specific boards, listens to the events you pick, and includes who did it plus a before and after changelog.

Your webhooks

Sign in with Discord to create webhooks.

Events

todo.createdA todo was created
todo.updatedA todo's title, description, priority, due date, tags or images changed
todo.movedA todo moved to another category
todo.completedA todo was marked as completed
todo.scrappedA todo was scrapped
todo.deletedA todo was deleted (it stays restorable in History)
todo.restoredA todo was restored from History
board.createdA board was created (account-wide webhooks only)
board.updatedA board's name, description, icon, colour or archive state changed
board.deletedA board and all its todos were deleted

Moves only fire when a todo changes category (reordering inside a column is quiet). Each board can have different webhooks, and a webhook set to “All boards” can be switched off for individual boards. A webhook.test event is sent when you press “Send test”.

Payload

Custom webhooks receive this JSON as a POST. changes lists every field that changed with its before and after value (category and tag ids are already resolved to names).

{
  "id": "1291204012871098368",
  "event": "todo.updated",
  "createdAt": "2026-10-05T12:30:00.000Z",
  "actor": {
    "userId": "80351110224678912",
    "username": "nelly",
    "displayName": "Nelly",
    "avatarUrl": "https://cdn.discordapp.com/avatars/…",
    "via": "api:1291199911112222333",
    "viaLabel": "API key “CI bot”"
  },
  "board": { "id": "1291200000000000001", "name": "Roadmap", "url": "https://your-domain/boards/1291200000000000001" },
  "todo": {
    "id": "1291200000000000002", "number": 12, "title": "Ship webhooks",
    "description": "…", "priority": "high", "state": "active",
    "category": "In progress", "tags": ["backend"], "dueAt": null,
    "attachments": [], "url": "https://your-domain/todo/1291200000000000002"
  },
  "changes": [
    { "field": "priority", "label": "Priority", "before": "medium", "after": "high" },
    { "field": "description", "label": "Description", "before": "Old text", "after": "New text" }
  ]
}
AuthorizationBearer <your API key>
X-Atlas-EventThe event name, e.g. todo.updated
X-Atlas-DeliveryUnique delivery id (same as the payload id)
X-Atlas-Signaturesha256=<HMAC-SHA256 of the raw body, keyed with your API key>
Content-Typeapplication/json

Verifying requests

Custom webhooks must have an API key. It is sent as a bearer token and used to sign each body, so check at least one of them before trusting a request.

import crypto from "node:crypto";

// Express-style handler. `raw` is the unparsed request body string.
function verify(raw, headers, apiKey) {
  if (headers.authorization !== `Bearer ${apiKey}`) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", apiKey).update(raw).digest("hex");
  const given = headers["x-atlas-signature"] ?? "";
  return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Discord & Slack

Paste a Discord webhook URL (Channel settings → Integrations → Webhooks) and messages are sent as Components v2: a coloured container with the actor's avatar, the changes as strikethrough or diff blocks, and an “Open todo” button. Mentions in todo text never ping anyone. Slack incoming-webhook URLs get the equivalent Block Kit message. Discord and Slack URLs are encrypted at rest and only ever shown masked.

Delivery & retries

Deliveries run in the background, so they never slow your requests down. A failed request is retried once (honouring Retry-After), results show under “Deliveries” for 14 days, and a webhook that fails 25 times in a row is switched off automatically. Custom endpoints must be public https hosts; redirects are not followed. At most 20 events are sent per action, so a very large bulk change is truncated.