Skip to main content

Webhooks

BXML webhooks are HTTP requests made by the Bandwidth platform to endpoints specified by you in your HTTP requests, BXML and in your Voice application. Their purpose is to:

  1. inform you of events that have happened in the call flow
  2. receive instructions from your application on what to do next.

Synchronous Webhooks

BXML webhooks are HTTP POST requests by default. The request will have a JSON body that describes the event and expect an XML response consisting of BXML verbs.

note

HTTP GET requests may be used for webhooks by setting the appropriate Method attribute when specifying each 's URL. If the GET method is used, the properties are passed as query parameters. This can cause very long URLs, so POST is the preferred method.

We use a 15s request timeout by default when trying to deliver all s. However, you can customize that value when creating an outbound call by setting a callbackTimeout on the request; or with application settings for inbound calls.

tip

Relative URLs are allowed in BXML verb attributes and they will be resolved against the URL of the server that provided the BXML containing the relative URL. For example, if we send an answer event to https://example.com/answer and the BXML sent back to us contains a Gather with a gatherUrl=/onGatherComplete, the gather event will be sent to https://example.com/onGatherComplete.

WebhookDescription
AnswerBandwidth API sends this when the call is answered.
Bridge CompleteBandwidth API sends this to the application when a <Bridge> is complete and the original call needs to continue.
Bridge Target CompleteBandwidth API sends this to the application when a <Bridge> is complete and the target call needs to continue.
GatherBandwidth API sends this when a <Gather> is completed.
InitiateBandwidth API sends this when an inbound call arrives.
Record CompleteBandwidth API sends this when a <Record> is completed. The recording is not available to download until the Recording Available event is received.
RedirectBandwidth API sends this when a <Redirect> is requested or when a POST request is made to the /calls/{callId} endpoint requesting a redirect.
Transfer AnswerBandwidth API sends this when the <Transfer> is answered.
Transfer CompleteBandwidth API sends this when the <Transfer> is complete and the original call needs to continue.
Conference CreatedBandwidth API sends this when a new conference is created.
Conference Member JoinBandwidth API sends this when a new member joins a conference.
Conference Member ExitBandwidth API sends this when a member leaves a conference.
Conference RedirectBandwidth API sends this to the application when a POST request is made to the /conferences/{conferenceId} endpoint requesting to modify a conference.

Asynchronous Webhooks

Asynchronous webhooks are HTTP requests made by the Bandwidth platform to endpoints specified by you in your HTTP requests and BXML. The HTTP POST method is used by default. The request will have a JSON body that describes the event. An HTTP 201 response with no content is expected. HTTP 200 is also acceptable. If there is a response body (including BXML), it will be ignored.

Asynchronous callbacks are retried once to their original URL in the event of a connection exception.

note

HTTP GET requests may be used for webhooks by setting the appropriate Method attribute when specifying each 's URL. If the GET method is used, the properties are passed as query parameters. This can cause very long URLs, so POST is the preferred method.

WebhookDescription
Conference CompletedBandwidth API sends this after the last member leaves the conference.
Conference Recording AvailableBandwidth API sends this when a recording started by a <StartRecording>in a conference is available for download.
DisconnectBandwidth API sends this when a call ends.
DTMFBandwidth API sends this for every digit detected after a <StartGather> is executed.
Machine Detection CompleteBandwidth API sends this when the result of a machine detection request is available.
MediaStreamStartedBandwidth API sends this after the stream requested in a <StartStream> is started.
MediaStreamRejectedBandwidth API sends this if a stream requested in a <StartStream> can not be started.
MediaStreamStoppedBandwidth API send this when a stream requested in a <StartStream> ends.
Recording AvailableBandwidth API sends this when a recording started by either a <StartRecording> or a <Record> verb in a call is available for download.
Transfer DisconnectBandwidth API sends this when any leg of a <Transfer> ends.
Transcription AvailableBandwidth API sends this when the transcription of a recording is available for download.