Skip to main content
POST
Create Webhook
Changes state - verify before retry Registers a URL endpoint to receive call notifications. When a call that was not started by a batch call ends, DialNexa sends an HTTP POST to your URL with a signed plain JSON payload. DialNexa does not encrypt the webhook body. The secret is required. Generate a long random value, store it in a secret manager, and send it only over HTTPS. The create response is the only response that exposes the unmasked value; get, list, and update responses return ********. The response wraps the new subscription in data.webhook. Its id has the webhook_ prefix; use that value with the get, update, and delete operations.

Payload delivered when a call ends

billing can be absent even for workspaces on the new billing system, because billing is recorded in the background while the delivery is being prepared. Read the call afterwards for its final charges.

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 (which are created without a batch link).
  • A delivery is sent when the call reaches one of the final statuses listed above. 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.
  • A completed call whose recording location is not yet known when the call ends may not be delivered. Do not rely on receiving a delivery for every ended call; reconcile with Get Call Details using the call ID.

Delivery behavior

  • Each delivery is one POST attempt. DialNexa does not retry a failed delivery and does not set a request timeout.
  • The response status your endpoint returns is not checked or stored. Return a 2xx quickly and do the work asynchronously.
  • Requests carry Content-Type: application/json and User-Agent: Nexa-SingleOutboundCall-Webhook/1.0.
  • A call can occasionally produce more than one delivery, for example when a later status upgrades an earlier final status to completed. Make your handler safe to run twice for the same call_id.

Verifying the signature

Every delivery includes an x-nexa-signature header:
Computed as HMAC-SHA256(secret, rawBody) over the raw request body. Always verify against the raw body before parsing JSON.
Node.js
Python

When to use this

  • Call outcome processing: get notified when a call that was not placed directly by a batch call ends instead of polling Get Call Details, then write the outcome to your CRM or trigger the next step.
  • Live dashboards: track call completions as they happen.

Available events

events must be a non-empty list of strings and is stored and returned as you sent it. Delivery is not filtered by it today: every active subscription in the workspace receives the call-ended delivery shown above, whatever its list contains, and the payload’s status field says how the call ended. Use call.completed so the subscription reads correctly when filtering is introduced; do not translate dots to underscores.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
url
string<uri>
required

The URL to which webhook events will be sent.

Example:

"https://webhook.site/your-endpoint"

events
string[]
required

List of events this webhook is subscribed to.

Minimum array length: 1
Example:
secret
string
required

Secret used to sign webhook payloads.

Example:

"replace-with-a-long-random-secret"

is_active
boolean

Whether the webhook is active.

Example:

true

Response

Webhook created successfully.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

201

message
string
required
Example:

"Success"

data
object
required
timestamp
string<date-time>
required