Webhooks

Our current implementation of Webhooks allows you to hook your own processing into Application and Channel level events. Each event trigger provides information on the client, connection or event that can be hooked into.

These events are detailed in the following sections.

Application Webhooks

Application Webhooks allow hooking into Application level events.

In your configuration console, add a new Application Webhook by clicking the NEW button in the Application configuration and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.

There are three event triggers which are detailed below.

Client Registered

This event triggers when a new client connects to an application ID.

Client Registered sample JSON object:

{
   "timestamp": 1562614545646,
   "origin": "client",
   "type": "client.registered",
   "client": {
      "applicationId": "my-app-id",
      "userId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceId": "9ffa994a648940b997ac79db343d0f7d",
      "deviceAlias": "camera 1",
      "id": "my-app-id/4531e51218b24fb58d5dc62087a93439",
      "clientTag": "1",
      "roles": ["role1", "role2"],
      "region": "en-us",
      "coreCount": 6,
      "architecture": "x64",
      "machineName": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36",
      "operatingSystem": "Windows 10",
      "operatingSystemVersion": "1809",
      "physicalMemory": "8589934592",
      "sourceLanguage": "typescript,
      "apiVersion": "0.0.0.0"
   }
}


Client Unregistered

This event triggers when a client unregisters from the gateway by leaving a channel.

Client Unregistered sample JSON object:

{
   "timestamp": 1562614545646,
   "origin": "client",
   "type": "client.unregistered",
   "client": {
      "applicationId": "my-app-id",
      "userId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "deviceId": "9ffa994a648940b997ac79db343d0f7d",
      "id": "my-app-id/4531e51218b24fb58d5dc62087a93439"
   }
}


Client Updated

This event triggers when a client's information is updated on the gateway (a username change, for example).

Client Updated sample JSON object:

{
   "timestamp": 1562614545646,
   "origin": "client",
   "type": "client.updated",
   "client": {
      "applicationId": "my-app-id",
      "userId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceId": "9ffa994a648940b997ac79db343d0f7d",
      "deviceAlias": "camera 1",
      "id": "my-app-id/4531e51218b24fb58d5dc62087a93439",
      "clientTag": "1",
      "roles": ["role1", "role2"],
      "region": "en-us",
      "coreCount": 6,
      "architecture": "x64",
      "machineName": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36",
      "operatingSystem": "Windows 10",
      "operatingSystemVersion": "1809",
      "physicalMemory": "8589934592",
      "sourceLanguage": "typescript,
      "apiVersion": "0.0.0.0"
   }
}


Channel Webhooks

Channel Webhooks allow hooking into Channel level events. 

Check out the webhook configuration section of your configuration console's channel configuration section. Channel webhooks can be added by clicking the NEW button in the Channel configuration and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.

There are nine event triggers which are detailed below.

Client Joined

"Client Joined" indicates that a client has joined a channel.

Client Joined sample JSON object:

{
   "timestamp": 1562614545646,
   "origin": "client",
   "type": "channel.joined",
   "channel": {
      applicationId: "my-app-id",
      "id": 123456
   },
   "client": {
      "applicationId": "my-app-id",
      "userId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "deviceId": "9ffa994a648940b997ac79db343d0f7d",
      "id": "my-app-id/4531e51218b24fb58d5dc62087a93439"
   }
}

Client Left

"Client Left" indicates that a client has left a channel.

Client Left sample JSON object:

{
   "timestamp": 1562614545646,
   "origin": "client",
   "type": "client.left",
   "channel": {
      "applicationId": "my-app-id",
      "id": 123456,
      "report": {
         "messagesSent": 24,
         "bytesSent": 288,
         "messagesReceived":24,
         "bytesReceived":288
      }
   },
   "client": {
      "applicationId": "my-app-id",
      "userId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "deviceId": "9ffa994a648940b997ac79db343d0f7d",
      "id": "my-app-id/4531e51218b24fb58d5dc62087a93439"
   }
}

Connection Initializing

"Connection Initializing" indicates that a connection is being initialized, but no connection attempts have been made.

Connection Initializing sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.initializing",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "initializing",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "transports": {},
      "localAudioMuted": false,
      "localVideoMuted": false,
   }
}

Connection Connecting

"Connection Connecting" indicates that a connection is currently connecting.

Connection Connecting sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.connecting",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "connecting",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
   }
}

Connection Connected

"Connection Connected" indicates that a connection is currently connected.

Connection Connected sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.connected",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "connected",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */   
   }
}

Connection Closing

"Connection Closing" indicates that a connection has been instructed to close and is cleaning up resources. For the empty properties below, see "Connection Connected".

Connection Closing sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.closing",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "clientRoles": ["role1", "role2"],
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "closing",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */  
   }
}

Connection Closed

"Connection Closed" indicates that a connection has completely closed and resources have been cleaned up.

Connection Closed sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.closed",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "videoDirection": "sendonly",
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "clientRoles": ["role1", "role2"],
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "closed",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */  
   }
}

Connection Failing

"Connection Failing" indicates that a connection has encountered an error and is cleaning up resources.

Connection Failing sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.failing",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "clientRoles": ["role1", "role2"],
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "failing",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "error": {
        "code": "ConnectionNotEstablished",
        "message": "Could not establish connectivity with remote peer. Shutting down connection.",
      },
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */   
   }
}

Connection Failed

"Connection Failed" indicates that a connection has encountered an error and has cleaned up resources.

Connection Failed sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.failed",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "clientRoles": ["role1", "role2"],
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "failed",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "error": {
        "code": "ConnectionNotEstablished",
        "message": "Could not establish connectivity with remote peer. Shutting down connection.",
      },
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */   
   }
}

Connection Updated

"Connection Updated" indicates that a connection's information has changed. 

Connection Updated sample JSON object:

{
   "timestamp": 1562614545646,
   "type": "connection.updated",
   "origin" : "client",
   "connection": {
      "id": "78139048613349c0bf4ed7adb70fd996",
      "applicationId": "my-app-id",
      "audioDirection": "sendonly",
      "audioFormats": [{
         "name": "",
         "clockRate": 48000,
         "channelCount": 1,
      }],
      "videoDirection": "sendonly",
      "videoFormats": [{
         "name": "",
         "clockRate": 5000,
         "channelCount": 1,
      }],
      "channelId": 123456,
      "clientId": "69a754b194474867bb36860b19391514",
      "clientTag": "1",
      "clientRoles": ["role1", "role2"],
      "dataDirection": "sendrecv",
      "deviceId", "d46bb0df25b641ce86e01c40487ad240",
      "userId", "d8c5a6527deb4cc6bf4afb908e682e5d",
      "userAlias": "stephen",
      "deviceAlias": "camera 1",
      "state": "updated",
      "tag": "sfu-upstream",
      "type": "sfu",
      "recording": false,
      "mediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteConnectionId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "remoteMediaId": "d8c5a6527deb4cc6bf4afb908e682e5d",
      "localAudioMuted": false,
      "localVideoMuted": false,
      "audioStreams": [...], /* Array of AudioStream Stats Objects  */
      "videoStreams": [...], /* Array of VideoStream Stats Objects */
      "dataStream": {...},   /* The DataStream Stats Objects  */
      "transports": [...]    /* Array of Transport Stats Objects  */  
   }
}

Connection Stats

Connection stats event triggers are detailed on a separate page here.