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 manage subscriptions via the v1 API.

Before you start

• A tenant API key with webhooks:write scope. Generate one in Settings → API Keys.
• If you only need to list subscriptions, use a tenant API key with webhooks:read scope.
• 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 the subscription — you’ll need it to verify signatures.

Create a subscription

POST https://YOUR-ATENDER-HOST/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):

{
  "id": "...",
  "name": "production-listener",
  "url": "https://your-server.example.com/atender-webhooks",
  "events": ["message.received", "message.sent", "conversation.resolved"],
  "secret": "whsec_...",
  "isActive": true,
  ...
}

The secret is returned only at creation time. Store it immediately — you cannot retrieve it later. If you lose it, rotate using POST /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) — 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.

Respond quickly

Your endpoint must respond within 10 seconds. The expected response is 2xx. Each event is delivered once — there is no automatic retry today, so treat webhooks as notifications and refetch authoritative state via the API rather than relying on every delivery arriving. (maxRetries and retryDelaySeconds are accepted and stored on the subscription for forward compatibility, but the dispatcher does not retry yet.)

After 10 consecutive failed deliveries, 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 — /v1/webhooks — List your tenant’s subscriptions. Includes delivery status and consecutive-failure count.
• GET — /v1/webhooks/:id — Get full details for one subscription, including custom headers and retry config.
• PATCH — /v1/webhooks/:id — Update name, URL, event list, active/paused state, retry config.
• DELETE — /v1/webhooks/:id — Permanently remove a subscription.
• POST — /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 failures. Check disableReason to understand why, fix your endpoint, then PATCH isActive: true to re-enable.

Limits

• Each tenant has a maxWebhooks limit (5 by default, adjustable per tenant). Trying to create more returns 403 LIMIT_EXCEEDED.

Troubleshooting

• Symptom: POST /v1/webhooks returns 403. Fix: Your API key lacks the webhooks:write scope, or you’ve hit the maxWebhooks limit. Check the response body’s error message (LIMIT_EXCEEDED vs a scope error) to tell which.

• Symptom: Subscription created but no events arrive. Fix: Confirm the subscription is isActive: true and not isPaused. Check lastDeliveryAt and lastDeliveryStatus to see whether Atender tried and failed, or whether nothing triggered yet.

• Symptom: The subscription got disabled. Fix: GET it and read disableReason — typically “auto-disabled after 10 consecutive failures”. Fix your endpoint, then PATCH isActive: true to 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.

See also

• REST API integration
• Webhook events reference
• Send an outbound message