Webhook Notifications

The EnableX video service includes a server-to-server notification system for sharing important events of a session and post processing updates. The notification system helps you to implement an effective and complete workflow of your application.

EnableX sends notification of important events to your application server through a Webhook. Once the Webhook is set up, your server will start receiving HTTP posts with raw body contents, which can be used for developing an effective and well integrated video application with EnableX.

Setting Up a Notification URL

A Notification URL is a project specific setting. Therefore, each project can have different Notification URL. However, you can use the same Notification URL with multiple projects. Events are sent to the Notification URLs in the JSON format. The JSON data contains the app_id of the project, which can be used to segregate data for each project.

To set up a Notification URL:

Log in to the Portal.
Navigate to Projects / My Projects.
In the left navigation pane, click Get Started under Video.
Select the project that you want to integrate with.
Choose whether you want low code integration or prefer to code yourself for the selected project.
Click the project. As a result, the Settings page is displayed.
Click the Manage configuration tab.
Click the Setup Webhook tab.
Enter the URL and click the Save button. Notifications from the platform will be sent to your Notification URL.

EnableX supports the HTTP Basic Authentication method for verifying webhooks. Basic authentication makes use of username and password for webhook producers to be authenticated when sending webhooks to a webhook URL. To use this authentication, select the HTTP Authentication checkbox and enter the credentials (related username and password) that you want EnableX to use for accessing your Webhook.

Advance Settings

Notification Events

Once the Notification Webhook URL is configured, EnableX sends the events (HTTP POST method with a raw body in the JSON format) to the configured URL to notify you about relevant events for your session and post session processing. The JSON body of the method contains a key named type, which contains a String Constant for different types of event notifications.

{
	"type": "String"	
	// Enumerated values for type given below
}

Enumerated Data for type

Enum	Description
`session_start`	When a new session starts in a Video Room.
`session_stop`	When an ongoing session in a Video Room stops/ends.
`roomdrop`	When CDR (Call Detail Report) is available for an ended session. You may call related Video API to get CDR.
`recording`	When individual user's recorded streams are available for download. The notification contains URLs of file(s) to pull/download.
`transcoded`	When single re-playable file(s) (transcoded from Individual Stream Recordings) are available for download. The notification contains URLs of file(s) to pull/download.
`live_recording`	When live-recording file(s) (Recorded Live in-Session using Custom-UI) are available for download. The notification contains URLs of file(s) to pull/download.
`chatdata`	When Chatscript File (In-Session Chat Data File) is available for download. The notification contains URL of file to pull/download.
`metadata`	When Meta Data File (Session Activity Data File) is available for download. The notification contains URL of file to pull/download.
`transcription`	When transcription file(s) are available for download. The notification contains URLs of file(s) to pull/download.
`file_transfer`	When file(s) are transferred to destination server through Delivery Service. The notification contains location of the transferred files in the destination server.

Session Started

EnableX notifies you when a session starts in the EnableX Video Room. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID, Conf Num, and so on.

For example:

{
  "type": "session_start",
  "trans_date": Number,		// In Unix Timestmamp (UTC) 
  "room_id": "String",		
  "conf_num": "String",
  "concurrent_sessions": {	// Infornatino on concurrent sessions 
    "license_sessions": {		
      "$license_id": boolean,	// License Numbers in active session 
      "$license_id": boolean
    },
    "total_sessions": Number,	// Total Ongoing Session 
    "max_sessions": Number	// Total allowed Concurrent Session 
  },
  "app_id": "String"
}

Note:

{"type": "session_start"} for Session Start Notification.
concurrent_sessions object is included only if you have subscribed for Concurrency based Billing Mode. - total_sessions denotes how many sessions are ongoing including the new session that got started.
license_sessions object is included if you have subscribed for User License based Billing Mode.

Session Ended

EnableX notifies you when a session ends in the EnableX Video Room. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID, Conf Num, and so on.

For example:

{
  "type": "session_stop",
  "trans_date": Number,		// In Unix Timestmamp (UTC)  
  "room_id": "String",		
  "conf_num": "String",
  "concurrent_sessions": {	// Infornatino on concurrent sessions  
    "license_sessions": {		
      "$license_id": boolean,	// License Numbers in active session  
      "$license_id": boolean
    },
    "total_sessions": Number,	// Total Ongoing Session  
    "max_sessions": Number	// Total allowed Concurrent Session  
  },
  "app_id": "String"
}

Note:

{ "type": "session_stop" } for Session End Notification.
concurrent_sessions object is included only if you have subscribed for Concurrency based Billing Mode.
total_sessions denotes how many sessions are ongoing after this session got closed.
license_sessions object is included if you have subscribed for User License based Billing Mode.
When you are notified with this event, CDR for the session is not ready. Any attempt to get CDR using API will fetch empty response. For CDR, you need to wait for “CDR Ready” event (explained below).

CDR Ready

EnableX notifies you when a CDR (Call Detail Repot) is available for your concluded sessions. CDR may be fetched using API and the report is made available in your EnableX Portal.

The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num.

For example:

{ 
	 "type": "roomdrop",
	 "trans_date": Number,	// In Unix Timestamp (UTC) 
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String" 
}

Note:

{ "type": "roomdrop" } for CDR Ready Notification. This was previously used for session drop. Its not renamed anyway to ensure backward compatibility.
In case your application needs to get Call Detail Report (CDR) for the concluded session, you can use Video API call on the conf_num data. The room_id and conf_num are two identifiable data using which CDR may be accessed using API.

Recording Files Ready

EnableX notifies you when a recording file is available for your concluded sessions. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with an array of recorded file paths.

For example:

{ 
	 “type”: “recording”,
	 “trans_date”: Number,	// In Unix Timestamp (UTC) 
	 “app_id”: “String”,
	 “room_id”: “String”,
	 “conf_num”: “String”,
	 “recording”: [ 
		"http://FQDN/path/file"
	 ]
}

Note:

{"type": "recording"} for Recording File Notification.
If your application needs store the recorded files locally, you can loop through the array and download each recorded file individually. The meta data of the session such as Room ID and Conf Num may be used for data reference.

Transcoded Files Ready

EnableX notifies when a file is transcoded and the transcoded file is available. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session along with the array of the transcoded file paths.

For example:

{ 
	 "type": "transcoded",
	 "trans_date": Number,	// In Unix Timestamp (UTC) 
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String",
	 "recording": "http://FQDN/path/file",
	 "stage": "String",	// Sequence of File within Session 
	 "file_size": "String", // In byte 
}

Note:

{ "type": "transcoded" } for Transcoded File Notification.
If your application needs store the transoded files locally, you can loop through the array and download each transcoded file individually. The meta data of the session such as Room ID and Conf Num may be used for data reference.

Live Recording Files Ready

EnableX notifies you when the live recording file is available. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with the URL from where the files are accessible and downloadable.

For example:

{ 
	 "type": "live_recording",
	 "trans_date": Number,	// In Unix Timestamp (UTC)  
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String",
	 "url": "http://FQDN/path/file",
	 "file_size": "String",	// In byte 
}

Note:

{ "type": "live_recording" } for Live Recording Notification.
In case your application needs to download the live-recording files to store locally, you can access the file through the url key in the JSON which contains the URL to download.
The room_id and conf_num may be used for data reference.

Chat Data File Ready

EnableX notifies you when the chat script file is available. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with the URL.

For example:

{ 
	 "type": "chatdata",
	 "trans_date": Number,	// In Unix Timestamp (UTC)  
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String",
	 "url": "http://FQDN/path/file"
}

Note:

{ "type": "chatdata" } for Chat Data Ready Notification.
In case your application needs to download the chat script file of the session to store locally, you can access the file through the url key in the JSON which contains the URL to download.
The room_id and conf_num may be used for data reference.

Meta Data File Ready

EnableX notifies you when the session meta data file is available. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with the URL.

For example:

{ 
	 "type": "metadata",
	 "trans_date": Number,	// In Unix Timestamp (UTC)  
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String",
	 "url": "http://FQDN/path/file"
}

Note:

{ "type": "metadata" } for Meta Data Ready Notification.
In case your application needs to download the meta data file of the session to store locally, you can access the file through the url key in the JSON which contains the URL to download.
The room_id and conf_num may be used for data reference.

Transcription File Ready

EnableX notifies you when the Transcription File is available. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with the URL.

For example:

{ 
	 "type": "transcription",
	 "trans_date": Number,	// In Unix Timestamp (UTC)  
	 "app_id": "String",
	 "room_id": "String",
	 "conf_num": "String",
	 "url": "http://FQDN/path/file"
}

Note:

{ "type": "transcription" } for Transcription Ready Notification.
In case your application needs to download the transcription file of the session to store locally, you can access the file through the url key in the JSON which contains the URL to download.
The room_id and conf_num may be used for data reference.

Recording or Transcoded Files Transferred

EnableX notifies you as soon as stream recording, transcoded, live recording, chat data, meta data or transcription file(s) are transferred to your location through our delivery service. The JSON body of the POST method sent to the Notification Webhook URL contains the meta data of the session such as Room ID and Conf Num along with the information about the destination server and the location of the transferred file.

For example:

{
	"type": "file-transfer",
	"trans_date": Number,	// In Unix Timestamp (UTC) 
	"app_id": "String",
	"room_id": "String",
	"conf_num": "String",
	"destination": {
		"name": "",	// Constants: awss3, ftp, sftp, ssh 
		"host": "",	// In case of ftp, sftp, ssh  
		"account": ""	// In case of awss3   
	},
	"files": [
		{ "url": "http://FQDN/path/file" }
	]
}

Note:

{"type": "file-transfer"} for File Transfer Notification.
The files array can contain one or more locations to store the transferred files.
The meta data of the session such as Room ID and Conf Num may be used for data reference.