Webhooks

This page covers dashboard webhooks: webhooks registered in the dashboard, attached to an agent, and signed with the x-dialnexa-signature header. Subscriptions created through the API with POST /v1/user-webhooks are a different system with a flat payload and an x-nexa-signature: sha256=<hex> header; see the v1 webhooks overview.

DialNexa sends webhook events to your endpoint using HTTP POST.

Quick start

Create a webhook secret and store it securely. A webhook cannot be registered until the workspace has an active webhook secret.
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. Registering a webhook requires an active webhook secret, so this request is always signed with it.
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, for the reasons marked hangup in Hangup reasons. A call that ends without connecting for any other reason does not produce this event. 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",
      "notes": null
    }
  }
}

`call_ended` with `status: "completed"`

Sent when a call completes. This payload can include transcript, summary, recording URL, and post-call analysis fields. Unlike call_initiated and the hangup variant, its payload also carries "event": "call_ended" next to call; transfer_completed carries "event": "transfer_completed" the same way. transcript is always a string. When the transcript is a list of messages, the string is that list encoded as JSON with system messages removed, so parse it with JSON.parse before reading turns. It is an empty string when no transcript was recorded. 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": {
    "event": "call_ended",
    "call": {
      "id": "call_abc123xyz",
      "type": "phone_call",
      "direction": "outbound",
      "status": "completed",
      "category": "batch_call",
      "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": "[{\"role\":\"assistant\",\"content\":\"Hello, thanks for calling DialNexa support...\"},{\"role\":\"user\",\"content\":\"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`

Sent when the call engine reports a phone transfer attempt. call_transfer.status is successful or failed. Warm transfers handled through a transfer session do not send this event.

{
  "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_call",
      "category_id": "batch_qyurbcy76471ud",
      "notes": null
    },
    "call_transfer": {
      "id": "transfer_trk8xq2m4n9p1w3",
      "transferred_at": "2025-05-02T10:19:40.000Z",
      "destination": "human",
      "status": "successful",
      "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": {
    "event": "call_ended",
    "call": {
      "id": "call_k7m2nq9xw4p8r1v3",
      "type": "phone_call",
      "direction": "outbound",
      "status": "completed",
      "category": "batch_call",
      "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": "[{\"role\":\"assistant\",\"content\":\"Hello, thanks for calling DialNexa support. How can I help you today?\"},{\"role\":\"user\",\"content\":\"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"
      },
      "notes": null
    },
    "call_transfer": {
      "id": "transfer_trk8xq2m4n9p1w3",
      "transferred_at": "2025-05-02T10:19:40.000Z",
      "destination": "human",
      "status": "successful",
      "destination_id": "13105554455",
      "duration_in_seconds": 62,
      "destination_call_id": null
    }
  }
}

Call category

payload.call.category tells you how the call was started, and category_id carries the related ID. The batch value differs by event, so match both spellings:

Call source	`call_initiated` and `call_ended` (`hangup`)	`call_ended` (`completed`) and `transfer_completed`	`category_id`
Batch call	`batch`	`batch_call`	`batch_<id>`
Workflow	`workflow`	`workflow`	`workflow_<id>`
Any other call, including single and inbound calls	`single_outbound`	`single_outbound`	`null`

Automatic retry attempts of a batch call are sent as single_outbound with category_id null. To relate a retry to its batch, use the original call you recorded (payload.call.id) and that call’s batch. agent_id is the agent ID with the agent_ prefix. On call_initiated and the hangup variant it can be the bare string agent_ when the telephony data for the call carries no agent ID. On transfer_completed it is an empty string in that case.

Hangup reasons

Every call_ended event carries hangup_reason. On the completed variant it is the reason stored on the call and can be null when none was recorded. 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.
`invalid_phone_number`	`hangup`	The carrier reported the destination number as invalid.
`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. A webhook cannot be registered without an active webhook secret, so every request is signed. 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.

Secret rotation and the grace window

Rotating a webhook secret from the dashboard replaces its key in place; see Webhook Secrets for the dashboard side. By default the previous key stays valid for 24 hours, and during that window every delivery carries two signature headers:

Header	Signed with
`x-dialnexa-signature`	The previous key, so a receiver that has not been updated yet keeps verifying.
`x-dialnexa-signature-new`	The new key.

When the window ends, x-dialnexa-signature switches to the new key and the extra header disappears. Rotating with the expire-now option skips the window entirely, and the old key stops working at once. Write your receiver to hold a list of configured keys and accept a delivery when any configured key verifies any signature header present. Add the new key alongside the old one when you rotate, then remove the old key after the window ends. A receiver written this way never rejects a valid event across a rotation. Verification requests sent when a webhook is saved are always signed with the current key only.

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

Rotation applies to one signing secret and only changes the webhooks that use it; it does not change whether any webhook is active. See Secret rotation and the grace window for how the old and new secrets overlap.

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)

Call category

Hangup reasons

Custom notes

Setting notes

Signature verification

Secret rotation and the grace window

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)

​Call category

​Hangup reasons

​Custom notes

​Setting notes

​Signature verification

​Secret rotation and the grace window

​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)

Call category

Hangup reasons

Custom notes

Setting notes

Signature verification

Secret rotation and the grace window

Verification checklist

Node.js example

Python example

Secret rotation

Register Webhook