Webhooks

BRTC supports webhooks to keep your application informed of Endpoint lifecycle events as they happen. When you create an Endpoint, you can specify an eventCallbackUrl and an eventFallbackUrl to receive notifications of these events. If the eventCallbackUrl is unreachable, Bandwidth will retry the webhook at the eventFallbackUrl.

Bandwidth expects a 2xx response from your eventCallbackUrl to consider the notification successful. If Bandwidth receives a non-2xx response, or if the eventCallbackUrl is unreachable, it will retry the webhook at the eventFallbackUrl.

Endpoint Connected

{
  "accountId": "9903498",
  "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "event": "endpointConnected",
  "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
  "timestamp": 1771537419412,
  "tags": "{\"myTag\": \"myTagValue\"}"
}

Endpoint Disconnected

{
  "accountId": "55001234",
  "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "event": "endpointDisconnected",
  "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
  "timestamp": 1771537419412,
  "tags": "{\"myTag\": \"myTagValue\"}"
}

Endpoint Eligible

{
  "accountId": "55001234",
  "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "event": "endpointEligible",
  "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
  "timestamp": 1771537419412,
  "tags": "{\"myTag\": \"myTagValue\"}"
}

Endpoint Ineligible

{
  "accountId": "55001234",
  "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "event": "endpointIneligible",
  "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
  "timestamp": 1771537400297,
  "tags": "{\"myTag\": \"myTagValue\"}"
}

Endpoint Outbound Connection Request

You will receive this webhook when a WebRTC Endpoint requests an outbound connection to a destination. The webhook will include the type and id of the requested destination, as well as the id of the Endpoint and Device that made the request. To allow the outbound connection request, you must create a call using the Bandwidth Calls API and connect it to the Endpoint that made the request using a <Connect> BXML verb with a destination of the Endpoint id that made the request.

{
  "accountId": "55001234",
  "toType": "PHONE_NUMBER",
  "fromType": "ENDPOINT",
  "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "from": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
  "to": "+16192100923",
  "event": "outboundConnectionRequest",
  "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
  "timestamp": 1771537400298,
  "tags": "{\"myTag\": \"myTagValue\"}"
}