Skip to main content
Webhooks created through the v1 API deliver a call-ended notification to your HTTPS endpoint. They are the preferred way to process call outcomes without aggressive polling.
These pages cover subscriptions created with POST /v1/user-webhooks, signed with the x-nexa-signature header. Webhooks registered in the dashboard and attached to an agent are a separate system with their own payload and x-dialnexa-signature header; see Dashboard webhooks.

​
Lifecycle

  1. Create Webhook with an HTTPS URL, an events list, and a long random secret.
  2. Store the secret immediately. It is shown only in the create response; get, list, and update responses mask it as ********.
  3. Verify the x-nexa-signature header against the raw request body before parsing JSON.
  4. Return a success response quickly and process durable work asynchronously.
  5. Update the URL, events, active state, or secret.
  6. Delete subscriptions that are permanently retired.

​
Which calls are delivered

Calls placed directly by a batch call do not trigger a delivery. Every other call does, including single calls, web calls, workflow calls, inbound calls, and automatic retry attempts. A completed call whose recording location is not yet known when the call ends may not be delivered, so do not rely on a delivery for every ended call. Calls refused before dialling, which end failed with end_reason dnc_blocked, spend_cap_reached or insufficient_balance, send no delivery; reconcile them with Get Call Details or List Calls. See Create Webhook for the payload and the full rules.

​
Delivery-safe consumer design

  • Each delivery is a single POST with no retry and no request timeout. If your endpoint is down, that delivery is lost; reconcile missed calls with Get Call Details using the call ID.
  • A call can occasionally produce more than one delivery, so make handlers tolerant of duplicates.
  • Do not assume deliveries arrive in business-time order.
  • Store the payload’s call_id before triggering downstream work.
  • Keep the raw body available for signature verification.
  • Use Get Webhook and List Webhooks to confirm configuration.

​
Event names

A subscription stores the events list you send and returns it unchanged. Today every active subscription receives one delivery when an eligible call ends, whatever the list contains; the payload’s status field says how the call ended. Use call.completed in the list and do not convert dots to underscores.