VIDIZMO Webhooks Reference Guide

Overview

VIDIZMO's Webhooks enable you to subscribe to the various events taking place within the VIDIZMO portal and receive notifications based on those events within your business application. This reduces or even eliminates the need to make recurrent calls to fetch updated data values using VIDIZMO API. Because you can now conveniently use Webhooks to be notified on the events in VIDIZMO Portal (video watched or video downloaded) using which you want to trigger some action on within your own business application.

VIDIZMO sends out these notifications using HTTP POST requests to the endpoint you configure in your app in VIDIZMO Portal.

Setting up Webhooks App

To enable Webhooks, you have to configure a Webhooks App in VIDIZMO Portal and specify the following information:

• A valid Endpoint URL where the notifications are to be sent. This is the designated URL of your application that will receive requests from VIDIZMO based on the events you have subscribed to.
• Event Subscriptions that define the events upon which you want VIDIZMO to send notifications to your application. You can choose from the list of available events by selecting the object (media/comments) and the associated events.
• Generate verification token from the app, which you can then use to validate the requests being sent to your notification endpoint. This verification token will be sent by VIDIZMO in the authorization header of the notification payload.
• An email address that will be used to notify stakeholder, incase a notification request is timed out after maximum number of retries - more of which has been covered in a separate section below.

After configuring the app, make sure to activate it in order to start receiving notification alerts on the subscribed events.

Events that can be Subscribed to

VIDIZMO has certain objects that contain data related to various resources in VIDIZMO Portal such as Portal's media or comments.

VIDIZMO allows you to subscribe to as many events related to an object as you want.

Media

Media is essentially every type of file or entity that can be ingested and created in VIDIZMO Portal that helps segregate content and users, as well as facilitates various wings of an organization to collaborate in a shared workspace.

VIDIZMO Media includes the following:

• Video files ingested in the system, that undergo advanced processing to generate meaningful insights;
• Audio files ingested in the system that can be auto-transcribed and indexed to increase reach;
• Document files ingested in the system that can be browsed in a rich viewer, and be searched through using advanced OCR (text extracted from images within a document as well). 
• Image files ingested in the system for central storage that can be annotated, rotated and analyzed using rich viewer tools.
• Playlists that help create a sequential series of audios and videos to create a rich playback experience for the viewers with features to auto-advance and enforce order.
• Collections that help create a browsable folder of various content that can not only be grouped together as one course, but creates a theatre like viewing experience for all files within.
• Quizzes that help evaluate users' understanding and progress for a corporate training course.
• Surveys that help capture leads and feedback of end-users with ultimate ease.

Below is a list of events associated with a Media.

Live Media

VIDIZMO empowers enterprises to broadcast live sessions with ultimate ease, allowing their streams to reach an unlimited number of public or private audience or selected users.

Below are a few events associated with a live webcast in VIDIZMO.

Quiz/Survey

VIDIZMO allows you to create multiple-page Quizzes and Surveys for your audience to evaluate how well do they grasp the gist of the media they have interacted with/watched, as well as to better engage them with your content and get their valuable feedback.

Below is the event associated with when a user submits Quiz or Survey in the Portal. 

Comment

VIDIZMO users can comment on a media to give their views and opinions about the media. Comments are a simple way to provide feedback or simply drop in a note. The comments feature allows you to post a new text comment, either to respond to the video or join in on a conversation already taking place. In VIDIZMO, any user with a Viewer+ role is able to add a comment from the Media's Playback page, given comments are enabled in the Portal as well as on the media. Similarly, Portal's authoritative users can choose to enable Comment Moderation that allows them to review and moderate every comment before it gets published in the Portal.

Below is a list of events associated with Comments in Portal.

Category

VIDIZMO provides the user to define a category or subcategory on the Portal-level for the media being published. This classifies, organizes and segregates the media content and facilitates the user in the search and sort of the relevant media. An authorized user is allowed to create, modify or delete a category or its sub-category. They can either be defined individually or in a hierarchy.

Below is a list of events associated with Categories in Portal.

Custom Attributes

VIDIZMO portal comes with a built-in set of attributes for defining the media content to be published or modified. Examples are Title, Categories, Tags, Description, and Author's name. VIDIZMO also provides the users to create additional fields uaing custom attribute feature to give complete control over defining the metadata for media content. This allows the uploader to classify the content in custom and creative ways, giving the users massive flexibility to search and sort the content. VIDIZMO also provides the ability to drag and drop the attribute to change it's position while displaying it to the uploader. To add Custom Attributes in your Portal, read more about it here: How to Manage Custom Attributes.

Below is a list of events associated with Custom Attributes in Portal.

Notification Payload Structure

As soon as a subscribed event is fired within the VIDIZMO Portal, we will trigger a notification payload request and send it to your specified Endpoint URL. This payload will be sent in the form of an HTTP POST request, which will include JSON object in its Request Body and headers to aid authorization.

Method Type: POST

Headers:

The request will contain multiple headers:

• Content-Type: application/json
• Authorization: This will contain a token generated for your app and confirms the validity of the request. To verify if a request is sent by VIDIZMO, you can compare this with the token being displayed under your Webhooks app in VIDIZMO Portal.

Request Body:

The Request Body contains information about the event you are being notified against.

This includes the event ID, title of the event, relevant information about the object (previous and current object if any of the properties were changed) and the action that took place on the object. 

Here is a sample object for event generated when a user updates their comment on a media:

{
  "id": "6672"
  "vidizmoEventId": "CommentUpdate",
  "eventDate": "2020-10-26T06:30:15.657",
  "ip": "136.135.169.234",
  "status": "Success",
  "description": ""
  "subjectType": "Video",
  "subjectId": 263482,
  "subjectTitle": "Annual Conference Summit 2019",
  "tenant": {...}, //Read more about the object here: https://help.vidizmo.com/en/support/solutions/articles/17000110689-api-reference-guide-tenantinfo-object
  "subjectDetail": "{\"Id\":7669,\"CommentModerationStatus\":\"PendingForApproval\",\"CommentContent\":\"This video's been the most interesting lesson I have learned.\",\"Mashup\":{\"Id\":263482,\"EstimatedDuration\":0,\"Title\":\"Annual Conference Summit 2019\",\"Weight\":0,\"Format\":\"All\",\"IsMyFlaggedMashup\":false},\"Tenant\":{\"Id\":18761,\"IsSSLEnable\":false,\"Weight\":0},\"AddedDateTime\":\"2020-10-26T06:29:22.69\",\"AddedBy\":{\"Id\":218003},\"UpdatedBy\":{\"Id\":218003},\"IsDeleted\":false}",
  "user": {...}, //Read more about the object here: https://help.vidizmo.com/en/support/solutions/articles/17000110691-api-reference-guide-userprofileinfo-object
  "isSystem": false
}

Request Fields: 

id: This is a number that uniquely identifies the event that took place in VIDIZMO Portal.

vidizmoEventID: A string that describes the event that has occurred.

eventDate: This is a UTC date and time for when the event took place.

IP: The IP Address from where the request was made.

isSystem: This bit identified whether this log has been generated by a user action or has been generated within a system automated workflow.

status: This implies that the event was successfully executed in the Portal.

description: This contains information about the event that took place in the Portal. It may or may not be populated depending upon the event in question.

subjectId: This contains the ID of the subject in question. For instance, whenever a comment is made or a media is uploaded - the ID of the media is registered here.

subjectType: This specifies the type of Object against which an event has occurred, such as Video or User. This has been covered in more details below.

subjectDetails: This includes the current state of the object with relevant properties, after the change caused during an event. 

tenant:  This contains basic information about the tenant associated with the subject under question – it helps establishing context of which Portal has the event been generated in.

user: The user object contains information about the user who carried out an action that triggered the event. It contains basic information such as ID, name, email address, etc.

Subject Types:

The SubjectType property can be one of the following values:

• Video
• Audio
• Document
• Image
• Collection
• Playlist
• Live
• Chat
• Category
• CustomAttribute
• PublishandViewSetting