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 key; the new secret is returned once. | 200 |
POST /v1/webhooks/{id}/test-delivery | Send a webhook.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.
| Field | Type | Rules | Required |
|---|---|---|---|
| url | string | Public HTTPS URL, 1 to 2048 characters. | Required on create |
| events | string[] | 1 to 50 event patterns, each 1 to 100 characters. | 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 to mint a new secret (the previous key stays valid for 24 hours so receivers can roll forward without an outage).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/wh_123 \
-H "Authorization: Bearer atlas_pat_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{"events":["task.completed","task.updated"],"disabled":false}'Rotate the signing key. The new secret is returned once in the response.
curl -X POST https://api.example.com/v1/webhooks/wh_123/rotate-key \
-H "Authorization: Bearer atlas_pat_REPLACE_ME"Send a webhook.test event to confirm the endpoint is reachable and your signature verification works.
curl -X POST https://api.example.com/v1/webhooks/wh_123/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.