Video Notification Webhook

The Enhanced Video Service notifies important events to your application server through a webhook. Once set up, you can start receiving HTTP posts with raw body contents and use them to develop an effective and well-integrated video application.

Table of Contents

Overview

The video service features a server-to-server notification service to share important session events and post-processing updates. This service helps you implement an effective and complete workflow for your application.

The application server is notified through an HTTP POST to a configured notification webhook 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 “Projects / My Projects”.
  • To get started with video services, go to “Get Started” under “Video” in the Left Bar. “Select Project” to choose whether you want low code integration or will prefer to code yourself for the selected project. In case if you have set this preference for your project, clicking on the project navigates to the “Settings” page.
  • Next, go to the “Setup Webhook” tab under the “Settings” option to set up a URL to receive Notifications from the platform.​
  • You get a form. Enter the URL and click submit to set up your Notification URL.
  • If you want to implement access security in your webhook, HTTP Basic Authentication is supported. You need to check the “HTTP Authentication” checkbox and enter the relevant username and password that must be used to access your webhook.

You are all set to receive Notification Events explained below:

Notification Events

Once your Notification Webhook URL is configured, an HTTP POST request with a JSON raw body will be sent to notify you about various events related to your session and post-session processing. The JSON body includes a key named type, which contains a string constant indicating the specific event notification.

{
	"type": "String" /* Constants: roomdrop, recording, transcoded, file-transfer */
}

Notification# 1: Session Ended

You will receive a notification as soon as a session ends in the Video Room. The JSON posted to the configured Notification Webhook URL as a raw body contains the session’s meta-information. (e.g. Room ID, Conf Num etc.).

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

Note: "type": "roomdrop" for Session End Notification.

In case your Application needs to get Call Detail Report (CDR) for the concluded Session, you can use Video API call on the conf_key data. The Room ID and Conf Num may be used to data reference.

Notification# 2: Recording File(s) Ready

You will be notified as soon as recording files become available for concluded sessions. The JSON posted to the configured Notification Webhook URL as a raw body contains the session’s meta-information (e.g., Room ID, Conference Number, etc.) along with an array of recorded file paths.

{ 
	 “type”: “recording”,
	 “trans_date”: “Unix Timestamp”,  /* In 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 may be used to data reference.

Notification# 3: Transcoded File(s) Ready

You will be notified as soon as any transcoding is completed and the transcoded files become available. The JSON posted to the configured Notification Webhook URL as a raw body contains the session’s meta-information (e.g., Room ID, Conference Number, etc.) along with an array of transcoded file paths.

{ 
	 "type": "transcoded",
	 "trans_date": "Unix Timestamp",  /* In 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 all transcoded files to store locally, you can do so by looping through the Array and download each file individually. The Room ID and Conf Num may be used to data reference.

Notification# 4: Recording / Transcoded File(s) Transferred

You will be notified as soon as a recording or transcoded file is transferred to your designated location through the Video Recording Delivery Service. The JSON posted to the configured Notification Webhook URL as a raw body contains session meta-information (e.g., Room ID, Conference Number, etc.), along with destination server details and the transferred file location.

{
	"type": "file-transfer",
	"trans_date": "Unix Timestamp", /* In 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.