Webhooks
Payloads and headers
Every delivery is one JSON event in the same envelope, sent with headers that name the event and prove it came from Atlas. This page describes both.
The event envelope
Every event, whatever its type, has the same outer shape. The resource itself sits in data.object, exactly as the API returns it, so the code that reads an API response can read a webhook too.
json
{
"id": "evt_cm1b7x0d80000lq8zf2a1k9e3",
"type": "task.updated",
"apiVersion": "2026-10-01",
"createdAt": "2026-10-01T09:30:12.418Z",
"tenantId": "cm0w5t8h10000lq8z0n4r7y2b",
"actor": {
"id": "cm0w5t8h10002lq8z9s3d6f1g",
"kind": "USER"
},
"data": {
"object": {
"id": "cm1a9z3c50007lq8z2x8v4b6n",
"projectId": "cm1a2k7p30004lq8z6j1q9w3e",
"title": "Publish the launch checklist",
"status": "IN_PROGRESS",
"priority": "HIGH",
"dueAt": "2026-10-03T17:00:00.000Z",
"createdAt": "2026-09-30T08:00:00.000Z",
"updatedAt": "2026-10-01T09:30:12.000Z"
},
"previousAttributes": {
"title": "Draft the launch checklist"
}
}
}| Field | Description |
|---|---|
id | The event id, beginning with evt_. It is the same on every attempt and every replay of the event, and it matches the Atlas-Event-Id header. |
type | The event name, such as task.updated. The full list is on the events page. |
apiVersion | The version of this envelope, currently 2026-10-01. A change that could break a receiver is released under a new version and announced in advance. |
createdAt | When the event happened, as an ISO 8601 timestamp in UTC. |
tenantId | The workspace the event belongs to. |
actor | Who caused the event. kind is USER for a person, AGENT for an automation or an assistant acting for a person, and SYSTEM for Atlas itself. id is the person or agent, and is null when the kind is SYSTEM. |
data.object | The resource as the API returns it at the moment the event was sent, with the same field names as a GET on that resource. For a permanent delete, the resource no longer exists, so the object carries only its id and deletedAt. |
data.previousAttributes | Present on an update. It holds the earlier value of each field that changed, and only those fields. Compare it with data.object to see exactly what changed. |
Read fields by name
Atlas may add fields to the envelope and to a resource without a new version. Read the fields you need by name, and ignore any field you do not recognise.
Headers
Every delivery carries these headers. They let you verify the delivery, skip a repeat, and route by event type before you parse the body. Header names are not case sensitive.
| Header | Description |
|---|---|
content-type | Always application/json. |
user-agent | Atlas-Webhooks/2. Useful for recognising Atlas in your access logs, but not a proof of origin: only the signature is. |
Atlas-Signature | t=<seconds>,v1=<hex>. Verify this before you trust the delivery. See Security and signing. |
Atlas-Timestamp | When this attempt was signed, in seconds since the Unix epoch. It equals t in the signature. |
Atlas-Event-Id | The event id. Record it and skip an event you have already processed: retries and replays carry the same id. |
Atlas-Event-Type | The event name, so you can route a delivery without parsing the body. |
Atlas-Delivery-Id | This delivery in your delivery log. A replay has a delivery id of its own. |
Atlas-Subscription-Id | The webhook this delivery was sent to. |
Worked example
One complete delivery: the request line, every header, a blank line, and the body exactly as it is sent, on a single line.
http
POST /atlas/webhook HTTP/1.1
Host: example.com
content-type: application/json
user-agent: Atlas-Webhooks/2
atlas-signature: t=1790933412,v1=<64 hexadecimal characters>
atlas-timestamp: 1790933412
atlas-event-id: evt_cm1b7x0d80000lq8zf2a1k9e3
atlas-event-type: task.updated
atlas-delivery-id: cm1b7x2k40003lq8z5d0v9h2e
atlas-subscription-id: cm1a4r9t20001lq8z3c7m6n1p
{"id":"evt_cm1b7x0d80000lq8zf2a1k9e3","type":"task.updated","apiVersion":"2026-10-01","createdAt":"2026-10-01T09:30:12.418Z","tenantId":"cm0w5t8h10000lq8z0n4r7y2b","actor":{"id":"cm0w5t8h10002lq8z9s3d6f1g","kind":"USER"},"data":{"object":{"id":"cm1a9z3c50007lq8z2x8v4b6n","projectId":"cm1a2k7p30004lq8z6j1q9w3e","title":"Publish the launch checklist","status":"IN_PROGRESS","priority":"HIGH","dueAt":"2026-10-03T17:00:00.000Z","createdAt":"2026-09-30T08:00:00.000Z","updatedAt":"2026-10-01T09:30:12.000Z"},"previousAttributes":{"title":"Draft the launch checklist"}}}