Webhooks

DialNexa sends webhook events to your endpoint using HTTP POST.

Quick start

Create a webhook secret and store it securely.
Register a webhook URL in the dashboard.
Return a 2xx status code to the verification request DialNexa sends the moment you save the URL. Until your endpoint does this, the webhook is not saved and no events are delivered.
Verify every incoming signature before processing events.
Parse event_type and handle the event-specific payload.

Request format

Every webhook request has this high-level structure:

{
  "event_type": "call_ended",
  "payload": {
    "call": {
      "id": "call_abc123xyz"
    }
  }
}

event_type: The event name used for routing.
payload: Event-specific data.

Supported event types

`verification`

Sent when you register a webhook URL, and again each time you change that URL. It is the first request your endpoint will ever receive from DialNexa, and the only event that is not tied to a call. Your endpoint must respond with a 2xx status code within the request timeout configured on the webhook. If it responds with anything else, times out, or is unreachable, DialNexa does not save the webhook and no call events are ever delivered to it.

{
  "event_type": "verification",
  "payload": {
    "message": "This is a verification request from DialNexa to ensure your webhook URL is reachable.",
    "timestamp": "2025-05-02T10:21:15.945Z"
  }
}

Field	Description
`payload.message`	Fixed text identifying the request as a reachability check.
`payload.timestamp`	UTC ISO 8601 time the verification request was sent.

How this event differs from call events:

payload is flat and contains no call object. Handlers that read payload.call.id without a guard will throw on this request, which fails verification and blocks the webhook from being saved.
The User-Agent header is DialNexa-External-Webhook-Verification/1.0. Every other event uses DialNexa-External-Webhook/1.0.
Signature verification works exactly as described in Signature verification. The x-dialnexa-signature header is present whenever your organization has a webhook secret, so create the secret before registering the URL if you want to test your signature check with this request.
Verification requests are not retried and do not appear in delivery logs. Retry settings apply only to call events.

The simplest endpoint that passes verification is one that returns 204 for any POST it can authenticate. Add event handling after that works.

`call_initiated`

Sent when a call starts.

{
  "event_type": "call_initiated",
  "payload": {
    "call": {
      "id": "call_abc123xyz",
      "direction":"outbound",
      "type": "phone_call",
      "category": "batch",
      "category_id": "batch_001",
      "from_number": "12137771234",
      "to_number": "12137771235",
      "status": "initiated",
      "agent_id": "agent_987654321",
      "initiated_at": "2025-05-02T10:21:15.945Z",
      "notes": {
        "crm_record_id": "rec_8812",
        "campaign_owner": "[email protected]"
      }
    }
  }
}

`call_ended` with `status: "hangup"`

Sent when a call ends without completing. The reason is in hangup_reason. It is always present on this event, and is also sent as disconnection_reason, a deprecated alias carrying the identical value. Read hangup_reason; treat disconnection_reason as legacy. See Hangup reasons for every value and what it means.

{
  "event_type": "call_ended",
  "payload": {
    "call": {
      "id": "call_abc123xyz",
      "direction": "outbound",
      "type": "phone_call",
      "status": "hangup",
      "category": "batch",
      "category_id": "batch_001",
      "from_number": "12137771234",
      "to_number": "12137771235",
      "agent_id": "agent_987654321",
      "initiated_at": "2025-05-02T10:21:15.945Z",
      "hangup_reason": "user_did_not_pick_up",
      "disconnection_reason": "user_did_not_pick_up"
    }
  }
}

`call_ended` with `status: "completed"`

Sent when a call completes. This payload can include transcript, summary, recording URL, and post-call analysis fields. On this event hangup_reason tells you who ended the conversation, rather than why the call failed. See Hangup reasons. Note it is not accompanied by a disconnection_reason alias; that field appears only on the hangup variant above.

recording_url values are pre-signed links and expire after 7 days.

{
  "event_type": "call_ended",
  "payload": {
    "call": {
      "id": "call_abc123xyz",
      "type": "phone_call",
      "direction": "outbound",
      "status": "completed",
      "category": "batch",
      "category_id": "batch_001",
      "from_number": "12137771234",
      "to_number": "12137771235",
      "agent_id": "agent_987654321",
      "hangup_at": "2025-05-02T10:21:15.945Z",
      "duration_in_seconds": 142,
      "hangup_reason": "user_disconnected",
      "transcript": "Agent: Hello, thanks for calling DialNexa support...\nUser: Hi, I need help with my account...",
      "summary": "Customer called to inquire about account billing. Agent resolved the issue and confirmed the next payment date.",
      "recording_url": "https://storage.dialnexa.com/recordings/call_abc123xyz.wav?se=2025-05-09T10%3A21%3A15Z&sig=...",
      "post_call_analysis": {
        "sentiment": "positive",
        "intent": "billing_inquiry",
        "resolution": "resolved"
      },
      "notes": {
        "crm_record_id": "rec_8812",
        "campaign_owner": "[email protected]"
      }
    }
  }
}

`transfer_completed`

For conversational agents using a Transfer node, this event is emitted when handoff is processed.

{
  "event_type": "transfer_completed",
  "payload": {
    "event": "transfer_completed",
    "call": {
      "id": "call_k7m2nq9xw4p8r1v3",
      "from_number": "13105551234",
      "to_number": "13105559876",
      "agent_id": "agent_8f3k2m9x7p1w4q6",
      "direction": "inbound",
      "category": "batch",
      "category_id": "batch_qyurbcy76471ud"
    },
    "call_transfer": {
      "id": "transfer_trk8xq2m4n9p1w3",
      "transferred_at": "2025-05-02T10:19:40.000Z",
      "destination": "human",
      "status": "connected",
      "destination_id": "13105554455",
      "destination_call_id": null
    }
  }
}

`call_ended` (transferred calls)

Completed transferred calls can include an additional call_transfer object for transfer metadata.

{
  "event_type": "call_ended",
  "payload": {
    "call": {
      "id": "call_k7m2nq9xw4p8r1v3",
      "type": "phone_call",
      "direction": "outbound",
      "status": "completed",
      "category": "batch",
      "category_id": "batch_qyurbcy76471ud",
      "from_number": "13105551234",
      "to_number": "13105559876",
      "agent_id": "agent_8f3k2m9x7p1w4q6",
      "hangup_at": "2025-05-02T10:21:15.945Z",
      "duration_in_seconds": 142,
      "hangup_reason": "user_disconnected",
      "transcript": {
        "Agent": "Hello, thanks for calling DialNexa support. How can I help you today?",
        "User": "Hi, I need to speak with someone about my last invoice."
      },
      "summary": "Customer requested a billing specialist. Call was transferred to the support queue; issue addressed after transfer.",
      "recording_url": "https://storage.dialnexa.com/recordings/call_k7m2nq9xw4p8r1v3.wav?se=2025-05-09T10%3A21%3A15Z&sig=a7f3c2e8910b4d6e8f0a2c4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6",
      "post_call_analysis": {
        "sentiment": "neutral",
        "intent": "billing_escalation",
        "resolution": "transferred"
      }
    },
    "call_transfer": {
      "id": "transfer_trk8xq2m4n9p1w3",
      "transferred_at": "2025-05-02T10:19:40.000Z",
      "destination": "human",
      "status": "connected",
      "destination_id": "13105554455",
      "duration_in_seconds": 62,
      "destination_call_id": null
    }
  }
}

Hangup reasons

Every call_ended event carries hangup_reason. What it describes depends on the variant:

status: "completed": the call connected and a conversation happened, so the reason says who hung up first.
status: "hangup": the call never reached a conversation, so the reason says why it did not connect.

The Sent on column below tells you which variant each value arrives on. New reasons may be added over time, so treat a value you do not recognize as valid rather than failing on it.

Value	Sent on	Meaning
`user_disconnected`	`completed`	The person on the call hung up first.
`agent_disconnected`	`completed`	The AI agent ended the call.
`user_did_not_pick_up`	`hangup`	Rang until timeout without being answered. The most common outbound outcome.
`user_busy`	`hangup`	The line was busy, or the recipient actively rejected the call.
`voicemail_detected`	`hangup`	An answering machine or voicemail greeting picked up instead of a person.
`user_unreachable`	`hangup`	The carrier reported a temporary failure and could not reach the recipient.
`unallocated_phone_number`	`hangup`	The number is not assigned to any subscriber. The carrier rejected the destination outright.
`network_failure`	`hangup`	A network-level error in the carrier path ended the call before it connected.
`sip_auth_failed`	`hangup`	Your own SIP trunk (BYOC) rejected our credentials. A trunk configuration problem, not a call problem.
`sip_trunk_unreachable`	`hangup`	Your own SIP trunk’s termination URI could not be reached. Also a trunk configuration problem.
`unknown`	both	No hangup cause was recorded for the call.

Custom notes

Every call event carries a notes field inside payload.call. It returns whatever JSON object you attached to the call when you created it, unchanged, and is null when you attached nothing. Use it to carry your own identifiers through the call and back, so your handler can match an event to a record on your side without keeping a lookup table of DialNexa call IDs.

"notes": {
  "crm_record_id": "rec_8812",
  "campaign_owner": "[email protected]",
  "retry_of_ticket": 4471
}

Behaviour	Detail
Events	`call_initiated`, both `call_ended` variants, and `transfer_completed`
Value when unset	`null`
Shape	A JSON object with at most 15 top-level keys. Nested values are unrestricted.
Modified by DialNexa	No. Stored and returned verbatim.
Used by the agent	No. Notes never reach the prompt, unlike `metadata`.

Setting notes

How you attach notes depends on how the call is placed:

Call source	How to set it
Single call	A `notes` object on the Create Call request body.
Batch call	A reserved `notes` column in the recipient file, holding a JSON object for that recipient.
Workflow lead	A reserved `notes` column in the lead file, read by the same parser as batches.

In a recipient or lead file, the notes column is reserved: it becomes the call’s notes rather than a dynamic variable. A cell holding a JSON object is stored as that object. Plain text is wrapped as {"text": "..."}. A cell that starts with { or [ but is not valid JSON fails the upload with a 400 rather than being stored as text, so a malformed object is never silently flattened.

Retries do not inherit notes. A retry call log is created fresh and copies the parent’s tags and metadata but not its notes, so webhook events for a retry report notes: null even when the original attempt carried them. Match retries to your records through payload.call.id and the original call instead.

notes and metadata are separate fields with separate jobs. metadata is injected into the agent’s prompt as {{variables}} and shapes what the agent says; notes is inert storage that only your webhook handler sees. Data the agent must not read belongs in notes; though since notes are sent to your endpoint on every event for the call, they are not a place for credentials or secrets either.

Signature verification

Every webhook POST includes an x-dialnexa-signature header. DialNexa computes this value as an HMAC-SHA256 hex digest over the entire request body (the raw JSON bytes sent in the POST) using your webhook secret as the key.

Sign and verify the full request body exactly as received. Do not hash only the inner payload object, and do not re-serialize a parsed JSON object unless you can guarantee byte-for-byte parity with what DialNexa sent.

Verification checklist

Read the x-dialnexa-signature header.
Read the raw request body as bytes (before JSON parsing).
Compute HMAC_SHA256(raw_request_body, WEBHOOK_SECRET).
Compare expected vs received signatures using a constant-time comparison.
Reject on mismatch, then parse JSON and handle event_type and payload.

Node.js example

import crypto from "crypto";
import express, { Request, Response } from "express";

const app = express();

/**
 * Verifies a DialNexa webhook signature against the raw request body.
 * Uses a constant-time compare to avoid timing attacks.
 */
export function verifyDialNexaSignature(
  rawBody: string | Buffer,
  receivedSignature: string,
  webhookSecret: string
) {
  const bodyBuffer =
    typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;

  const expectedSignature = crypto
    .createHmac("sha256", webhookSecret)
    .update(bodyBuffer)
    .digest("hex");

  const expectedBuffer = Buffer.from(expectedSignature, "utf8");
  const receivedBuffer = Buffer.from(receivedSignature || "", "utf8");

  if (expectedBuffer.length !== receivedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (req: Request, res: Response) => {
    const receivedSignature = req.headers["x-dialnexa-signature"] as string;
    const rawBody = req.body as Buffer;

    if (!verifyDialNexaSignature(rawBody, receivedSignature, process.env.DIALNEXA_WEBHOOK_SECRET!)) {
      return res.status(401).send("Invalid signature");
    }

    const body = JSON.parse(rawBody.toString("utf8"));
    // Handle body.event_type and body.payload
    return res.sendStatus(204);
  }
);

Python example

import hashlib
import hmac
import json
import os

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()


def verify_dialnexa_signature(
    raw_body: bytes, received_signature: str, webhook_secret: str
) -> bool:
    """Verify DialNexa webhook signature for the full request body."""
    expected_signature = hmac.new(
        webhook_secret.encode(),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected_signature, received_signature or "")


@app.post("/webhook")
async def handle_webhook(request: Request):
    raw_body = await request.body()
    received_signature = request.headers.get("x-dialnexa-signature")

    if not verify_dialnexa_signature(
        raw_body,
        received_signature or "",
        os.environ["DIALNEXA_WEBHOOK_SECRET"],
    ):
        return JSONResponse(status_code=401, content={"message": "Unauthorized"})

    body = json.loads(raw_body.decode("utf-8"))
    # Handle body["event_type"] and body["payload"]
    return JSONResponse(status_code=204)

Secret rotation

Rotating your webhook secret updates all webhooks in your organization immediately. The old secret is deactivated and the new secret takes effect right away.

Update your webhook server configuration to use the new secret before or immediately after rotation.
Keep deployment steps ready to avoid signature mismatches during rollout.
Validate signature checks in staging before rotating in production.

Register Webhook

All webhook configuration is managed through the DialNexa dashboard, no API calls required.

Overview

Endpoints

Quick start

Request format

Supported event types

`verification`

`call_initiated`

`call_ended` with `status: "hangup"`

`call_ended` with `status: "completed"`

`transfer_completed`

`call_ended` (transferred calls)

Hangup reasons

Custom notes

Setting notes

Signature verification

Verification checklist

Node.js example

Python example

Secret rotation

Register Webhook

​Quick start

​Request format

​Supported event types

​verification

​call_initiated

​call_ended with status: "hangup"

​call_ended with status: "completed"

​transfer_completed

​call_ended (transferred calls)

​Hangup reasons

​Custom notes

​Setting notes

​Signature verification

​Verification checklist

​Node.js example

​Python example

​Secret rotation

​Register Webhook

Quick start

Request format

Supported event types

`verification`

`call_initiated`

`call_ended` with `status: "hangup"`

`call_ended` with `status: "completed"`

`transfer_completed`

`call_ended` (transferred calls)

Hangup reasons

Custom notes

Setting notes

Signature verification

Verification checklist

Node.js example

Python example

Secret rotation

Register Webhook