Webhooks

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.

note

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

note

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...

Property	Description
event	one of onConnect, onDisconnect or onLeave
timestamp	a Timestamp of the event, in milliseconds
participantId	The ID of the Participant that registered the callbackUrl
deviceId	The 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.

Examples

an onLeave event

POST http://yourUrl.com/participantEvent
Content-Type: application/json

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