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; a non-2xx response is treated the same as an unreachable URL and triggers a retry at the eventFallbackUrl.

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

When the endpoint becomes ineligible because of an error, or is torn down for good, the callback also includes errorId and errorMessage. errorId is one of:

errorId	Meaning
endpoint_disconnected	The endpoint's device connection disconnected and can never take another call on it again.
call_session_rejected	The endpoint's call session was rejected outright and is no longer usable.
sip_ack_timeout	The endpoint's call session could not be established in time.
peer_connection_failed	The endpoint's media connection failed unexpectedly.
media_setup_failed	The endpoint failed to set up its media connection.

errorMessage is a plain-English description of the failure, followed by guidance to provision a new endpoint and wait for endpointEligible before using it. errorId and errorMessage are omitted when the endpoint becomes ineligible for a routine reason (for example, going busy mid-call) and is expected to become eligible again.

{
    "accountId": "55001234",
    "endpointId": "e-0a223cf4-04f4-48e7-a706-7e84995f071e",
    "event": "endpointIneligible",
    "deviceId": "d-61f77cc8-78fe-58ad-913e-d76fb41eaab1",
    "timestamp": 1771537400297,
    "tags": "{\"myTag\": \"myTagValue\"}",
    "errorId": "call_session_rejected",
    "errorMessage": "The endpoint's call session ended unexpectedly and is no longer usable. This endpoint is ineligible and should not be reused. Provision a newly minted endpoint and wait for the endpointEligible callback before use."
}

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

See the BRTC FAQs for common questions about Endpoint lifecycle and connectivity.