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\"}"
}

Connect Status

The Connect Status event is fired when a <Connect> verb reaches a terminal outcome. These callbacks are sent to the eventCallbackUrl specified on the <Connect> verb. The status can be one of the following values:

• INITIATED: the connect method is in progress.
• COMPLETED: the call completed successfully.
• TIMED_OUT: the destination did not answer within the allowed time.
• DENIED: this account is not permitted to use this endpoint.
• CANCELED: the call was canceled before it completed.
• FAILED: an error occurred while connecting the call.

Property	Description
event	The event type, value is connectStatus.
timestamp	The Unix epoch time (in milliseconds) at which Bandwidth published this event.
status	The outcome of the connect attempt. See above for possible values.
accountId	The user account associated with the call.
eventCallbackUrl	(optional) The primary URL configured on the <Connect> verb. Omitted when not set on the verb.
eventFallbackUrl	(optional) The fallback URL configured on the <Connect> verb. Omitted when not set on the verb.
from	The originating endpoint or SIP URI of the connect attempt.
fromType	The type of the from party (e.g. ENDPOINT).
fromTags	(optional) Opaque tags associated with the from endpoint. Present only when from is a BRTC endpoint.
to	The destination endpoint or SIP URI of the connect attempt.
toType	The type of the to party (e.g. ENDPOINT).
toTags	(optional) Opaque tags associated with the to endpoint. Present only when to is a BRTC endpoint.

POST http://yourUrl.example/connectStatus
Content-Type: application/json

{
    "event"            : "connectStatus",
    "timestamp"        : 1714242612345,
    "status"           : "COMPLETED",
    "accountId"        : "55555555",
    "eventCallbackUrl" : "http://yourUrl.example/connectStatus",
    "eventFallbackUrl" : "http://fallback.example/connectStatus",
    "from"             : "sip:alice@example.com",
    "fromType"         : "ENDPOINT",
    "fromTags"         : "from-tag",
    "to"               : "sip:bob@example.com",
    "toType"           : "ENDPOINT",
    "toTags"           : "to-tag"
}

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\"}"
}