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:
- inform you of events that have happened in the call flow
- 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.
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 GET 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.
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.
| Webhook | Description |
|---|---|
| Answer | Bandwidth API sends this when the call is answered. |
| Bridge Complete | Bandwidth API sends this to the application when a <Bridge> is complete and the original call needs to continue. |
| Bridge Target Complete | Bandwidth API sends this to the application when a <Bridge> is complete and the target call needs to continue. |
| Gather | Bandwidth API sends this when a <Gather> is completed. |
| Initiate | Bandwidth API sends this when an inbound call arrives. |
| Record Complete | Bandwidth API sends this when a <Record> is completed. The recording is not available to download until the Recording Available event is received. |
| Redirect | Bandwidth API sends this when a <Redirect> is requested or when a POST request is made to the /calls/{callId} endpoint requesting a redirect. |
| Transfer Answer | Bandwidth API sends this when the <Transfer> is answered. |
| Transfer Complete | Bandwidth API sends this when the <Transfer> is complete and the original call needs to continue. |
| Conference Created | Bandwidth API sends this when a new conference is created. |
| Conference Member Join | Bandwidth API sends this when a new member joins a conference. |
| Conference Member Exit | Bandwidth API sends this when a member leaves a conference. |
| Conference Redirect | Bandwidth 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.
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 GET is the preferred method.
| Webhook | Description |
|---|---|
| Conference Completed | Bandwidth API sends this after the last member leaves the conference. |
| Conference Recording Available | Bandwidth API sends this when a recording started by a <StartRecording>in a conference is available for download. |
| Disconnect | Bandwidth API sends this when a call ends. |
| DTMF | Bandwidth API sends this for every digit detected after a <StartGather> is executed. |
| Machine Detection Complete | Bandwidth API sends this when the result of a machine detection request is available. |
| MediaStreamStarted | Bandwidth API sends this after the stream requested in a <StartStream> is started. |
| MediaStreamRejected | Bandwidth API sends this if a stream requested in a <StartStream> can not be started. |
| MediaStreamStopped | Bandwidth API send this when a stream requested in a <StartStream> ends. |
| Recording Available | Bandwidth API sends this when a recording started by either a <StartRecording> or a <Record> verb in a call is available for download. |
| Transfer Disconnect | Bandwidth API sends this when any leg of a <Transfer> ends. |
| Transcription Available | Bandwidth API sends this when the transcription of a recording is available for download. |