Webhook Setup

What is a Webhook?

A webhook lets Vaani push call events to your server in real time - no polling required. You’ll receive an HTTP POST request to your endpoint whenever a call lifecycle event occurs (e.g. call started, ended, transferred, or post-processed).

Event Types

Vaani fires webhooks for both outbound and inbound calls.

Event	Outbound	Inbound	Description
`call_started`	Yes	Yes	Call initiated / inbound participant connected
`call_ringing`	Yes	No	Phone is actively ringing
`user_picked_up_at`	Yes	Yes	User answered the call
`call_rejected`	Yes	No	User rejected or line was busy
`call_no_answer`	Yes	No	No answer after ~45 s timeout
`call_failed`	Yes	No	SIP error or abrupt abort
`human_transfer_initiated`	Yes	Yes	Call transfer to human agent triggered
`human_transfer_successful`	Yes	Yes	Warm transfer connected to specialist
`human_transfer_failed`	Yes	Yes	Warm transfer failed (rejected / busy / no-answer)
`call_ended`	Yes	Yes	Session terminated - `call_duration` in seconds
`call_postprocessing`	Yes	Yes	Summary, transcript & entities ready - `call_duration` in seconds

Setup

Create a Webhook Endpoint

Set up an HTTP endpoint on your server that accepts POST requests and returns 200 OK.

from flask import Flask, request

app = Flask(__name__)

@app.route("/vaani/webhook", methods=["POST"])
def handle_webhook():
    payload = request.json
    event = payload.get("event")

    data = payload.get("data", {})

    if event == "call_ended":
        print(f"Call {data.get('room_name')} ended after {data.get('call_duration')}s")
    elif event == "call_postprocessing":
        print(f"Transcript: {data['transcript']}")
        print(f"Summary:    {data['summary']}")
    elif event == "human_transfer_initiated":
        print(f"Transferring to {data.get('phone_number')}")

    return {"status": "ok"}, 200

Go to Settings → Webhooks and add your endpoint URL.

Your webhook endpoint must be publicly accessible. For local development, use a tunnel like ngrok.

Delivery

	Call lifecycle events	`call_postprocessing`
Timeout	5 seconds	10 seconds
Attempts	Up to 3 (retries after 1 s, then 2 s)	1, no retry
No retry on	`401`, `403`, `404` responses	any failure
Signature	`X-Webhook-Signature: <hex>`	`X-Webhook-Signature: sha256=<hex>`

Signatures are only sent when the webhook has a secret. Always respond with a 2xx quickly and make your handler idempotent.

Payload Reference

Every event is delivered as a JSON object with the same outer envelope. Event-specific fields live inside data:

{
  "event": "call_ended",
  "timestamp": "2026-07-24T13:34:22.278854+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": { "...": "event-specific fields" }
}

to and from are the called and calling numbers: for an outbound call to is the user and from is your agent’s number, for an inbound call it is the other way round. If the webhook has a secret, the request carries an X-Webhook-Signature header with the HMAC-SHA256 hex digest of the raw body (no sha256= prefix for these events). The per-event examples below show the complete delivered payload for each event.

call_postprocessing is sent by a different component than the other events and has a slightly different envelope (shown at the end of this page), with call_id, timestamp and data at the top level. Its signature header is X-Webhook-Signature: sha256=<hex>.

Outbound Call Events

`call_started`

Fired as soon as the SIP participant joins the room and the call begins dialing. For inbound and WebRTC calls the data carries caller instead of phone_number, and call_type is Inbound, WebRTC_Inbound or WebRTC_Outbound.

{
  "event": "call_started",
  "timestamp": "2026-07-24T13:33:10.120394+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210",
    "call_type": "Outbound",
    "agent_name": "my-sales-agent"
  }
}

`call_ringing`

Fired when the carrier reports the phone is actively ringing at the destination.

{
  "event": "call_ringing",
  "timestamp": "2026-07-24T13:33:12.481203+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210"
  }
}

Lifecycle Success Events

`user_picked_up_at`

Fired when the user answers and media starts flowing.

{
  "event": "user_picked_up_at",
  "timestamp": "2026-07-24T13:33:14.002871+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210",
    "picked_up_at": "2026-07-24T13:33:14.001522"
  }
}

Lifecycle Terminal Errors (Outbound Only)

`call_rejected`

Fired if the user manually rejects the call.

{
  "event": "call_rejected",
  "timestamp": "2026-07-24T13:33:15.310942+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210",
    "reason": "USER_REJECTED"
  }
}

`call_no_answer`

Fired if the call is not answered. reason is USER_UNAVAILABLE when the carrier reports the user unavailable, or TIMEOUT when nobody picks up within the ~45 second ring timeout.

{
  "event": "call_no_answer",
  "timestamp": "2026-07-24T13:33:58.884120+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210",
    "reason": "TIMEOUT"
  }
}

`call_failed`

Fired for SIP errors, technical failures or when the line ends in a failed state. reason is SIP_ERROR or INTERNAL_ERROR (both also carry error_code and error_message), or the final call status reported by the carrier.

{
  "event": "call_failed",
  "timestamp": "2026-07-24T13:33:11.774510+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "phone_number": "+919876543210",
    "reason": "SIP_ERROR",
    "error_code": "<error code>",
    "error_message": "SIP Error: <carrier message>"
  }
}

When the carrier reports the line as busy, the agent sends call_user_busy (same data as above, with reason set to the call status) instead of call_failed. call_user_busy is not on the list of events you can subscribe to in the dashboard, so only integrations whose webhook accepts it will see it.

Human Agent Transfer Events

summary in these events is the context summary the AI agent passes to the human.

`human_transfer_initiated`

Fired when the AI agent triggers the transfer_call tool to hand off the session.

{
  "event": "human_transfer_initiated",
  "timestamp": "2026-07-24T13:34:01.220918+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "transfer_type": "warm",
    "phone_number": "+919800000000",
    "summary": "Customer wants to discuss a refund."
  }
}

`human_transfer_successful`

Fired when the human specialist answers and the AI agent is ready to introduce the call (warm transfers).

{
  "event": "human_transfer_successful",
  "timestamp": "2026-07-24T13:34:12.640311+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "transfer_type": "warm",
    "phone_number": "+919800000000",
    "agent_identity": "human_agent_1712485300",
    "summary": "Customer wants to discuss a refund."
  }
}

`human_transfer_failed`

Fired if the transfer cannot be completed. reason is rejected_or_busy (with sip_status) for a warm transfer the human did not accept, cold_transfer_failed or transfer_error (with error) otherwise.

{
  "event": "human_transfer_failed",
  "timestamp": "2026-07-24T13:34:20.502764+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "transfer_type": "warm",
    "phone_number": "+919800000000",
    "agent_identity": "human_agent_1712485300",
    "reason": "rejected_or_busy",
    "sip_status": "busy",
    "summary": "Customer wants to discuss a refund."
  }
}

Session Termination & Analysis

`call_ended`

Fired as soon as the room is disconnected and the session terminates.

call_duration in this event is expressed in seconds.

end_reason is a descriptive string, not a fixed enum. Observed values include "Call ended" (normal hang-up) and "User went silent - Call Timed out"; do not match on an exact list. technical_issue is true when the call ended because of an error on our side or the carrier.

{
  "event": "call_ended",
  "timestamp": "2026-07-24T13:34:00.918374+00:00",
  "to": "+919876543210",
  "from": "+911234567890",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "end_reason": "Call ended",
    "call_duration": 42.5,
    "technical_issue": false,
    "transcript": "[13:33:14] AGENT: Hi! you have reached our customer service...",
    "phone_number": "+919876543210"
  }
}

`call_postprocessing`

Fired after the session ends and the backend has completed transcription, summary generation, and entity extraction.

call_duration in this event is expressed in seconds (a float rounded to 2 decimals), the same unit as call_ended. transcript and summary are inside data.

call_postprocessing is sent only for calls that went through analysis. It is not sent when the call was too short (under 1 second), had no transcript, the user never spoke (for example end_reason: "User went silent - Call Timed out"), or the call never connected (no answer, rejected, failed). Use call_ended (or Get Call Details) for those calls. entities and dispositions are null unless the agent has data extraction / dispositions configured. recording_url is a signed link that ends in ?token=...; use it as returned.

{
  "event": "call_postprocessing",
  "call_id": "outbound-1784899978-36cec598",
  "timestamp": "2026-07-24T13:34:22.278854+00:00",
  "data": {
    "room_name": "outbound-1784899978-36cec598",
    "call_id": "outbound-1784899978-36cec598",
    "call_duration": 55.15,
    "end_reason": "Call ended",
    "summary": "The user called to have their name recorded. The agent confirmed the name as Ayush Awasthi and noted it in the system. The conversation concluded successfully with no further requests.",
    "entities": {
      "name": "Ayush Awasthi"
    },
    "dispositions": {
      "acas": "Name Collected"
    },
    "recording_url": "https://uat.vaaniresearch.com/api/stream/outbound-1784899978-36cec598",
    "transcript": "[13:33:14] AGENT: Hi! you have reached our customer service. I am your assistant, how can I help you today?\n\n[13:33:19] USER: Yeah. How are you? What can you do for me?\n\n[13:33:31] AGENT: I am doing great, thank you for asking! I can help you with scheduling callbacks, transferring you to specific departments, or answering any questions you might have. How can I assist you today, Ayush?\n\n[13:33:33] USER: Can you take down my name?\n\n[13:33:37] AGENT: I actually have your name registered as Ayush Awasthi. Is that correct?\n\n[13:33:42] USER: Yes. Yes. That's the correct name. Please send that to your disposition.\n\n[13:33:47] AGENT: Got it, Ayush! I've noted that down. Is there anything else I can help you with today?\n\n[13:33:51] USER: No. No. No. That's it, I think. So much.\n\n[13:33:55] AGENT: You're very welcome! Have a wonderful day ahead!\n\n[13:33:57] USER: Bye bye.\n\n[13:34:00] AGENT: Goodbye! Have a wonderful day ahead!"
  }
}

Get Started

Create an Agent

Configuring Your Agent

Telephony & Studio

Guides & Capabilities

What is a Webhook?

Event Types

Setup

Delivery

Payload Reference

Outbound Call Events

`call_started`

`call_ringing`

Lifecycle Success Events

`user_picked_up_at`

Lifecycle Terminal Errors (Outbound Only)

`call_rejected`

`call_no_answer`

`call_failed`

Human Agent Transfer Events

`human_transfer_initiated`

`human_transfer_successful`

`human_transfer_failed`

Session Termination & Analysis

`call_ended`

`call_postprocessing`

​What is a Webhook?

​Event Types

​Setup

​Delivery

​Payload Reference

​Outbound Call Events

​call_started

​call_ringing

​Lifecycle Success Events

​user_picked_up_at

​Lifecycle Terminal Errors (Outbound Only)

​call_rejected

​call_no_answer

​call_failed

​Human Agent Transfer Events

​human_transfer_initiated

​human_transfer_successful

​human_transfer_failed

​Session Termination & Analysis

​call_ended

​call_postprocessing

What is a Webhook?

Event Types

Setup

Delivery

Payload Reference

Outbound Call Events

`call_started`

`call_ringing`

Lifecycle Success Events

`user_picked_up_at`

Lifecycle Terminal Errors (Outbound Only)

`call_rejected`

`call_no_answer`

`call_failed`

Human Agent Transfer Events

`human_transfer_initiated`

`human_transfer_successful`

`human_transfer_failed`

Session Termination & Analysis

`call_ended`

`call_postprocessing`