Skip to main content


Subscribing to Webhooks

Participant Creation (beta)

The only API call that allows the registration of a callback / webhook is the POST to the createParticipants endpoint that is used to create a new Participant. If the callbackUrl property is included in the payload, the value associated with that property is assumed to be a URL which, if found to be valid, will be invoked on events that occur as part of the Participant life cycle.


Participant event webhooks are currently in Beta, and must be activated by submitting a support ticket to Bandwidth.


Participant event webhooks may change in the future. All attempts will be made to retain the syntax and semantics of the current implementation, but until Bandwidth completes the process of learning with our customers that the implementation is optimal, we cannot guarantee it. Bandwidth welcomes any and all comments on the implementation while in the Beta phase.

Life Cycle Events

The events that will trigger invocation of the specified URL are:

  • onConnect - establishment of a signaling connection to allow control of the flow of WebRTC Media.
  • onLeave - removal of the signaling connection, prompted by server or client action.
  • onDisconnect - loss of the signaling connection, possibly due to loss of IP connectivity, or departure of the client. This may be coincident with an onLeave event.

Request Payload

The callback URL will be invoked by Bandwidth when the above events are detected. It will result in a POST to the URL specified as the value associated with the callbackUrl parameter. The Request Payload parameters that will be included in the POST body are...

eventone of onConnect, onDisconnect or onLeave
timestampa Timestamp of the event, in milliseconds
participantIdThe ID of the Participant that registered the callbackUrl
deviceIdThe id of actual device exchanging media
tag(optional) The tag specified on Participant creation. If no tag was specified this field will not be present.


an onLeave event

Content-Type: application/json

"event" : "onLeave",
"timestamp" : "1628786234676",
"participantId": "473f6544-92f7-4d67-9e77-bf2533cfff6d",
"deviceId" : "be199214-1a03-402a-a7b6-d002470a0465",
"tag" : "hello-world-phone"