Skip to main content
POST
/
user-webhooks
Register a webhook
curl --request POST \
  --url https://api.dialnexa.com/v1/user-webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://yourapp.com/webhooks/dialnexa",
  "events": [
    "call.completed",
    "call.failed",
    "campaign.completed"
  ],
  "secret": "whsec_your_secret_here",
  "is_active": true
}
'
{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/dialnexa",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "is_active": true,
  "created_at": "2024-03-01T10:00:00.000Z"
}
Registers a URL endpoint to receive event notifications. When subscribed events occur, such as a call completing or a campaign finishing, DialNexa sends an HTTP POST to your URL with a signed JSON payload.

​
How webhook verification works

Every request DialNexa sends to your endpoint includes an X-DialNexa-Signature header. This is an HMAC-SHA256 signature of the raw request body, generated using the secret you provide when registering the webhook. Verify this signature on your server to confirm the request is genuinely from DialNexa and hasn’t been tampered with. 
import hmac, hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(secret.encode(), payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

​
Available events

EventTriggered when
call.completedA call ends successfully.
call.failedA call attempt fails.
call.no_answerNo one picks up within the ring timeout.
campaign.completedAll leads in a campaign have been called.
campaign.pausedA campaign is paused.
workflow.lead.completedA lead finishes all steps in a workflow.

​
Request example

{
  "url": "https://yourapp.com/webhooks/dialnexa",
  "events": ["call.completed", "call.failed"],
  "secret": "whsec_your_random_secret_here",
  "is_active": true
}

​
Request

curl "https://api.dialnexa.com/v1/user-webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

​
Response

{
  "id": "whk_c9v3nz8rq4pm",
  "url": "https://yourapp.com/webhooks/dialnexa",
  "events": ["call.completed", "call.failed"],
  "is_active": true,
  "created_at": "2024-04-01T08:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Body

application/json
​
url
string<uri>
required

The HTTPS endpoint that will receive event payloads.

Example:

"https://yourapp.com/webhooks/dialnexa"

​
events
string[]
required

List of event types to subscribe to.

Example:
[
  "call.completed",
  "call.failed",
  "campaign.completed"
]
​
secret
string
required

A secret string used to sign webhook payloads. Verify the X-DialNexa-Signature header on incoming requests against this secret.

Example:

"whsec_your_secret_here"

​
is_active
boolean
default:true

Whether this webhook should receive events immediately.

Response

201 - application/json

Created.

​
id
string
Example:

"wh_abc123"

​
url
string
Example:

"https://yourapp.com/webhooks/dialnexa"

​
events
string[]
Example:
["call.completed", "call.failed"]
​
is_active
boolean
Example:

true

​
created_at
string<date-time>
Example:

"2024-03-01T10:00:00.000Z"