Voice API Webhooks Reference

Vonage uses webhooks alongside its Voice API to enable your application to interact with the call. There are two required, and one optional, webhook endpoints:

• Answer webhook is sent when a call is answered. This is for both incoming and outgoing calls.
• Event webhook is sent for all the events that occur during a call. Your application can log, react to or ignore each event type.
• Fallback URL is used when either the Answer or Event webhook fails or returns an HTTP error status.
• Errors are also delivered to the event webhook endpoint if they occur.

For more general information, check out our webhooks guide.

Signed Webhooks

Signed webhooks are a way to verify that the request is coming from Vonage and its payload has not been tampered with during transit. Voice API, as well as Messages and Dispatch APIs, support signed callbacks by default. See Decoding signed webhooks to learn how to decode an incoming JWT signature.

Answer Webhook

When an incoming call is answered, an HTTP request is sent to the answer_url you specified when setting up the application. For outgoing calls, specify the answer_url when you make the call.

By default, the answer webhook will be a GET request but this can be overridden to POST by setting the answer_method field. For incoming calls, you configure these values when you create the application. For outgoing calls, you specify these values when making a call.

Answer webhook data fields

Transmitting additional data with SIP headers

In addition to the above fields, you can specify any additional headers you need when using SIP Connect. Any headers provided must start with X- and will be sent to your answer_url with a prefix of SipHeader_. For example, if you add a header of X-UserId with a value of 1938ND9, Vonage will add SipHeader_X-UserId=1938ND9 to the request made to your answer_url.

Answer webhook data field examples

For a GET request, the variables will be in the URL, like this:

/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9

If you set the answer_method to POST then you will receive the request with JSON format data in the body:

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "SipHeader_X-UserId": "1938ND9"
}

Responding to the answer webhook

Vonage expect you to return an NCCO in JSON format containing the actions to perform.

Event webhook

Event webhook HTTP requests will arrive at the event webhook endpoint when there is any status change for a call. The URL will be the event_url you specified when creating your application unless you override it by setting a specific event_url when starting a call.

By default, the incoming requests are POST requests with a JSON body. You can override the method to GET by configuring the event_method in addition to the event_url. It is expected that your system will respond to the HTTP request. If your system doesn't acknowledge the event or instead responds with a 429, 502, 503 or a 504 a retry will be attempted. For events that require a NCCO to be returned, the fallback URL will then be used. Refer to the fallback URL section for further details.

The format of the data included depends on which event has occurred:

• started
• ringing
• answered
• busy
• cancelled
• unanswered
• disconnected
• rejected
• failed
• human/machine
• timeout
• completed
• record
• input
• transfer

Started

Indicates that the call has been created.

Back to event webhooks list

Ringing

The call destination is ringing.

Back to event webhooks list

Answered

The call was answered.

Back to event webhooks list

Busy

The destination is on the line with another caller.

Back to event webhooks list

Cancelled

An outgoing call is cancelled by the originator before being answered.

Back to event webhooks list

Unanswered

Either the recipient is unreachable or the recipient declined the call.

Back to event webhooks list

Disconnected

If the WebSocket connection is terminated from the application side for any reason then the disconnected event callback will be sent, if the response contains an NCCO then this will be processed, if no NCCO is present then normal execution will continue.

Back to event webhooks list

Rejected

The call was rejected by Vonage before it was connected.

Back to event webhooks list

Failed

The outgoing call could not be connected.

Back to event webhooks list

Human / Machine

For an outbound call made programmatically, if the machine_detection option is set then an event with a status of human or machine will be sent depending whether a person answered the call or not.

Back to event webhooks list

Timeout

If the duration of the ringing phase exceeds the specified ringing_timeout duration, this event will be sent.

Back to event webhooks list

Completed

The call is over, this event also includes summary data about the call.

Back to event webhooks list

Record

This webhook arrives when an NCCO with a "record" action has finished. When creating a record action, you can set a different eventUrl for this event to be sent to. This can be useful if you want to use separate code to handle this event type.

Transcription

Back to event webhooks list

Input

This webhook is sent by Vonage when an NCCO with an action of "input" has finished.

DTMF Capturing Results

Speech Recognition Results

Transcript text

See also complete example payload shown in NCCO Reference

Back to event webhooks list

Transfer

This webhook is sent by Vonage when a leg has been transferred from one conversation to another. This can be done using an NCCO or the transfer action

Back to event webhooks list

Fallback URL

The fallback webhook is accessed when either the answer webhook or the event webhook, when the event is expected to respond with an NCCO, returns an HTTP error status or is unreachable. The data that is returned from the fallback URL is the same as would be received in the original answer URL or event URL, with the addition of two new parameters, reason and original_request:

{
  "reason": "Connection closed.",
  "original_request": {
    "url": "https://api.example.com/webhooks/event",
    "type": "event"
  }
}

If there was a connection closed or reset, timeout or an HTTP status code of 429, 503 or 504 during the initial NCCO the answer_url is attempted twice, then:

1. Attempt to reach the fallback_answer_url twice
2. If no success, then the call is terminated

If there was a connection closed or reset, timeout or an HTTP status code of 429, 503 or 504 during a call in progress the event_url for events that are expected to return an NCCO (e.g. return for an input or notify action) is attempted twice, then:

1. Attempt to reach the fallback_answer_url twice
2. If no success, continue the call flow

Errors

The event endpoint will also receive webhooks in the event of an error. This can be useful when debugging your application.