Subscribe to webhook events
Webhook subscriptions let Atender notify your server when something happens — a new message arrived, a conversation was resolved, an SLA was breached. You can create and manage subscriptions in Settings → Integrations → Webhooks, or automate them with the v1 API.
Before you start
- To manage subscriptions in the UI, go to Settings → Integrations → Webhooks.
- To manage subscriptions with the API, use a tenant API key with
webhooks:writescope. Generate one in Settings → API & MCP. - If you only need to list subscriptions with the API, use a tenant API key with
webhooks:readscope. - To subscribe to
issue.*events, the API key needs theissues:readscope. In the UI, you need the View issues permission. - A public HTTPS endpoint on your server that can receive POST requests and respond quickly (under 10 seconds).
- A way to store the webhook secret Atender returns when you create or rotate the subscription — you’ll need it to verify signatures.
Create a subscription
Use Settings → Integrations → Webhooks to create a subscription without writing code. The settings screen can create, edit, pause, start, re-enable, and delete subscriptions. It can also rotate the signing secret. The secret is shown only when you create a subscription or rotate its secret — store it immediately because you cannot retrieve it later.
For automation, create a subscription with the API:
POST https://YOUR-ATENDER-HOST/api/v1/webhooks
Headers:
Authorization: Bearer sa_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Body:
{
"name": "production-listener",
"url": "https://your-server.example.com/atender-webhooks",
"events": [
"message.received",
"message.sent",
"conversation.resolved"
]
}
Response (201 Created). Every v1 response wraps its payload in a data object —
read body.data, not body:
{
"data": {
"id": "...",
"name": "production-listener",
"url": "https://your-server.example.com/atender-webhooks",
"secret": "whsec_...",
"events": ["message.received", "message.sent", "conversation.resolved"],
"isActive": true,
"customHeaders": {},
"createdAt": "2026-05-11T09:00:00.000Z"
}
}
The secret is returned only at creation time. Store it immediately — you cannot retrieve it later. If you lose it, rotate it in Settings → Integrations → Webhooks or with POST /api/v1/webhooks/:id/rotate-secret.
What your server receives
When a subscribed event fires, Atender POSTs your URL with a JSON envelope:
{
"event": "message.received",
"eventId": "5f0c2a1e-7d4b-4c9a-9a1f-3e8b6d2c4f10",
"deliveredAt": "2026-05-11T09:00:00.000Z",
"payload": { ... }
}
The exact payload shape depends on the event — see Webhook events reference.
Every delivery carries these headers:
Content-Type: application/json
User-Agent: Atender-Webhooks/1.0
X-Webhook-Event: message.received
X-Webhook-Delivery: 5f0c2a1e-7d4b-4c9a-9a1f-3e8b6d2c4f10
X-Webhook-Signature: sha256=<hex digest>
X-Webhook-Delivery is a unique delivery UUID (the same value as eventId in the body). It stays the same across every retry of a delivery, so use it to deduplicate.
Verify signatures
Every webhook delivery is signed using the subscription secret. Verify the signature before trusting the payload — otherwise anyone who knows your endpoint can forge events.
The signature is sent in the X-Webhook-Signature header as sha256=<hex digest>. Compute the HMAC-SHA256 of the raw request body using your subscription’s secret (the whsec_... value) as the key, hex-encode it, and compare it to the header value after the sha256= prefix. If it matches, the request is genuine.
Each retry attempt is signed afresh, so the signature can differ between attempts of the same delivery. Verify every attempt on its own.
Respond quickly
Your endpoint must respond within 10 seconds. The expected response is 2xx. Delivery is at-least-once: if an attempt fails, Atender retries, for up to 4 attempts in total, waiting 1, 2 and 4 minutes between attempts. Every attempt carries the same X-Webhook-Delivery ID and a fresh signature. Because of retries, an event can arrive twice, and events can arrive out of order — deduplicate on X-Webhook-Delivery and refetch authoritative state via the API when order matters. (maxRetries and retryDelaySeconds are not accepted on the subscription body — sending either one returns a 400 that names the field, because the retry schedule is fixed.)
A delivery that fails every attempt shows as failed. You can read these with GET /api/v1/webhooks/{id}/deliveries?status=failed, and Settings → Integrations → Webhooks shows a failure line under the webhook.
After 10 deliveries in a row that fail every attempt, the subscription is disabled automatically — you can see why under disableReason when you GET the subscription.
Best practice: acknowledge the delivery immediately with a 200 OK, then process the event in a background job. Don’t do heavy work in the webhook handler itself.
List, update, delete
GET—/api/v1/webhooks— List your tenant’s subscriptions. Includes delivery status and consecutive-failure count.GET—/api/v1/webhooks/:id— Get full details for one subscription, including custom headers, delivery status and disable reason.GET—/api/v1/webhooks/:id/deliveries— List deliveries for a subscription. Filter with?status=failedto see deliveries that failed every attempt.PATCH—/api/v1/webhooks/:id— Update name, URL, event list, active/paused state, custom headers.DELETE—/api/v1/webhooks/:id— Permanently remove a subscription.POST—/api/v1/webhooks/:id/rotate-secret— Generate a new signing secret. Returns the new secret in the response — old secret immediately stops working.
All require webhooks:write except GET which requires webhooks:read.
Pause vs disable
A paused subscription receives no deliveries but remains in your tenant — useful for temporary maintenance or debugging.
A disabled subscription was paused automatically by Atender after too many consecutive failed deliveries. Check disableReason to understand why, fix your endpoint, then PATCH isActive: true to re-enable.
Limits
- Each tenant has a
maxWebhookslimit (5 by default, adjustable per tenant). Trying to create more returns403 LIMIT_EXCEEDED.
Troubleshooting
-
Symptom: POST /api/v1/webhooks returns 403. Fix: Your API key lacks the
webhooks:writescope, or you’ve hit themaxWebhookslimit. Check the response body’s error message (LIMIT_EXCEEDEDvs a scope error) to tell which. -
Symptom: Subscription created but no events arrive. Fix: Confirm the subscription is
isActive: trueand notisPaused. ChecklastDeliveryAtandlastDeliveryStatusto see whether Atender tried and failed, or whether nothing triggered yet. You can also list failed deliveries withGET /api/v1/webhooks/{id}/deliveries?status=failed. -
Symptom: The subscription got disabled. Fix: GET it and read
disableReason— typically “auto-disabled after 10 consecutive failures”. Fix your endpoint, then PATCHisActive: trueto re-enable. -
Symptom: Signature verification fails. Fix: Make sure you’re computing HMAC-SHA256 over the raw request body, not the parsed JSON. Many web frameworks parse the body before you see it — most have a way to retain the raw bytes.