Webhooks
Managing via API
Provision and operate your webhook subscriptions over the public REST API: create endpoints, rotate signing keys, replay or test deliveries, and audit the delivery feed. Every route is scoped and role-gated so automation stays least-privilege.
Authentication
Webhook management is a privileged, workspace-wide surface. It is gated by both scope and role.
Requires webhooks:manage and OWNER or ADMIN
webhooks:manage scope, and the caller must be a workspace OWNER or ADMIN. See Authentication for minting a scoped token.Endpoints
Nine routes cover the full lifecycle: subscription CRUD, key rotation, delivery inspection, replay, and a test send. Paths are relative to your API base URL.
| Method and path | Purpose | Success |
|---|---|---|
GET /v1/webhooks | List subscriptions (signing secret is never returned). | 200 |
POST /v1/webhooks | Create a subscription; returns { webhook, secret } with the secret shown once. | 201 |
PATCH /v1/webhooks/{id} | Update url, events, ownerLabel, escalation fields, or disabled. | 200 |
DELETE /v1/webhooks/{id} | Delete a subscription. | 204 |
GET /v1/webhooks/{id}/deliveries | Delivery history for one webhook (limit query, default 50, max 200). | 200 |
POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay | Replay a past delivery. | 202 |
POST /v1/webhooks/{id}/rotate-key | Rotate the signing secret; the new secret is returned once. | 200 |
POST /v1/webhooks/{id}/test-delivery | Send a subscription.test event to the endpoint. | 202 |
GET /v1/webhook-deliveries | Workspace-wide delivery feed (limit query, default 50, max 200). | 200 |
Request fields
Create and update share the same field set. On create, url and events are required; on update, send only the fields you want to change and at least one must be present. A workspace can hold up to 100 webhooks, counting paused ones; at the limit, create answers 409 with a limit field.
| Field | Type | Rules | Required |
|---|---|---|---|
| url | string | Public HTTPS URL, 1 to 2048 characters. | Required on create |
| events | string[] | 1 to 50 patterns, each 1 to 64 characters: an event name from the catalogue, a resource wildcard such as task.*, or * for every event. | Required on create |
| ownerLabel | string or null | Up to 120 characters. | Optional |
| escalationEmail | string or null | Valid email address, up to 320 characters. | Optional |
| escalationNote | string or null | Up to 400 characters. | Optional |
| disabled | boolean | Pause or resume delivery without deleting the subscription. | Update only |
The signing secret is shown once
POST /v1/webhooks returns the HMAC signing secret exactly once, inside the secret field of the response. It is stored encrypted at rest, is never returned by any other endpoint, and cannot be retrieved later. Store it securely on receipt. If you lose it, call rotate-key for a new one. The previous secret keeps signing alongside the new one for 58 hours and 45 minutes, so your receiver can move to the new secret without missing a delivery.Examples
Replace atlas_pat_REPLACE_ME with a token that carries the webhooks:manage scope, and https://api.example.com with your API base URL.
Create a subscription. The response body is { webhook, secret }; capture secret now.
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"],"ownerLabel":"Platform team","escalationEmail":"oncall@example.com"}'List every subscription in the workspace. The signing secret is omitted from the list shape.
curl https://api.example.com/v1/webhooks \
-H "Authorization: Bearer atlas_pat_REPLACE_ME"Update the events a subscription listens for and re-enable it.
curl -X PATCH https://api.example.com/v1/webhooks/cm1a4r9t20001lq8z3c7m6n1p \
-H "Authorization: Bearer atlas_pat_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{"events":["task.completed","task.updated"],"disabled":false}'Rotate the signing secret. The response carries id, signingKeyVersion, the new secret, shown this once, and previousSigningKeyExpiresAt, when the old secret stops signing.
curl -X POST https://api.example.com/v1/webhooks/cm1a4r9t20001lq8z3c7m6n1p/rotate-key \
-H "Authorization: Bearer atlas_pat_REPLACE_ME"Send a subscription.test event to confirm that the endpoint is reachable and that your signature verification works.
curl -X POST https://api.example.com/v1/webhooks/cm1a4r9t20001lq8z3c7m6n1p/test-delivery \
-H "Authorization: Bearer atlas_pat_REPLACE_ME"Full reference
The summary above is a working guide, not the contract.
For every parameter, response field, and status code generated directly from the OpenAPI spec, see the live API reference. It lists these endpoints in full and stays in lockstep with the deployed API.