Enhanced Video Service notifies many important events to your Application Server through a Webhook. Once setup, you can start receiving HTTP Posts with Raw Body Contents and use them to develop an effective and well integrated Video Application with EnableX.

Table of Contents

Overview

EnableX Video Service features a Server-to-Server Notification Service to share important events of a Session and Post Processing updates. This Service helps you to implement an effective and complete workflow of your application.

EnableX notifies your Application Server through a HTTP POST to a configured Notification Web Hook URL.

Setup Notification URL

A Notification URL is a Project specific setting. Therefore, each project can have different Notification URL. However, you are free to use the same Notification URL against multiple projects to get notified. Note that the JSON Data posted to the Notification URL, will carry the app_id of the Project which you can use to segregate data for each project.

To setup Notification URL:

  • Login to the Portal
  • Navigate to “Video / Get Started”.
  • Choose your Project from the drop-down given and click “Go”.
  • Next, go to the “Webhook” tab.​
  • You get a form. Enter the URL and click submit to set up your Notification URL.
  • Select the events for which you are Notification to be posted on your Webhook.
  • In case you look to implement Access Security in your Webhook, EnableX supports HTTP Basic Authentication. You need to check the “HTTP Authentication” checkbox and enter related username & password that EnableX must use to access your Webhook.

You are all set to receive Notification Events explained below:

Notification Events

Once you configured your Notification Webhook URL, EnableX does HTTP POST with JSON Raw Body to the URL to notify you on few events related to your Session and Post Session Processing. The JSON Body contains a key named type which contains a String Constant for different type of event notification.

{
	"type": "String" /* Enum: roomdrop, recording, transcoded, file-transfer etc. */
}

Enumerated Data for “type”

EnumDescription
session_startWhen a new session starts in a Video Room
session_stopWhen an ongoing session in a Video Room stops/ends
roomdropWhen CDR (Call Detail Report) is available for an ended session. You may call related Video API to get CDR.
recordingWhen individual user’s recorded streams are available for download. The notification contains URLs of file(s) to pull/download.
transcodedWhen 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_recordingWhen 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.
chatdataWhen Chatscript File (In-Session Chat Data File) is available for download. The notification contains URL of file to pull/download.
metadataWhen Meta Data File (Session Activity Data File) is available for download. The notification contains URL of file to pull/download.
transcriptionWhen 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.

Notification# 1: Session Started

EnableX notifies you instantly as and when a session starts in EnableX Video Room. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.).

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

Notification# 2: Session Ended

EnableX notifies you instantly any session ends in EnableX Video Room. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.).

{
  "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).

Notification# 3: CDR Ready

EnableX notifies you as soon as CDR (Call Detail Repot) is ready to be fetched for the ended session. CDR may be fetched using API and same report is made available in EnableX Portal.

The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.).

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

Note:

  • { "type": "roomdrop" } for CDR Reay 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.

Notification# 4: Stream Recording File(s) Ready

EnableX notifies you as soon as any Stream Recording file(s) are available for download. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with an Array of Recorded File URLs from where the files are accessible and downloadable.

{ 
	 “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.
  • In case your application needs to download all recorded files to store locally, you can do so by looping through the Array and download each file individually.
  • The room_id and conf_num are used for data reference.

Notification# 5: Transcoded File(s) Ready

EnableX notifies you as soon as any transcoding is done and the transcoded file(s) are available to you. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with URL from where the files are accessible and downloadable.

{ 
	 "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.
  • In case your Application needs to download the transcoded files to store locally, you can access the file through the recording key in the JSON which contains the URL to download.
  • The room_id and conf_num may be used for data reference.

Notification# 6: Live Recording File(s) Ready

EnableX notifies you as soon as any Session Live Recording file is available to you. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with URL from where the files are accessible and downloadable.

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

Notification# 7: Chat Data File Ready

EnableX notifies you as soon as the Chat Script File is available to you. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with file URL.

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

Notification# 8: Meta Data File Ready

EnableX notifies you as soon as the Session Meta Data File is available to you. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with file URL.

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

Notification# 9: Transcription File Ready

EnableX notifies you as soon as the Transcription File is available to you. The JSON posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with file URL.

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

Notification# 10: File(s) 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 posted to Notification Webhook URL as Raw Body contains META information of the Session (e.g. room_id, conf_num etc.) along with Destination Server Information and transferred file location.

{
	"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 may contain one or many transferred files new location on the destination.
  • The room_id and conf_num may be used to data reference.