New feature: Video on demand webhooks

Today we are pleased to announce the launch of video on demand (VOD) webhooks. Webhooks are automated alerts that tell you when an event has occurred (like when your phone tells you you have a new email). Automatic notifications will simplify the development process - by removing the need to poll api.video for updates. Today’s announcement includes an alert for when a video has been encoded.

The problem we are solving

When you upload a video to api.video, we’ll immediately respond with information about the video. Inside the response, the assets object provides links for the thumbnail, the mp4 and for the streaming video, as an m3u8 stream, or our player - both standalone and in an iframe:

{
	"videoId": "vi1UQBDAMqAPCRxB3dmw1thc",
	"title": "Big Buck Bunny",
	<snip>
	"assets": {
		"iframe": "<iframe src=\"https://embed.api.video/vod/vi1UQBDAMqAPCRxB3dmw1thc\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"></iframe>",
		"player": "https://embed.api.video/vod/vi1UQBDAMqAPCRxB3dmw1thc",
		"hls": "https://cdn.api.video/vod/vi1UQBDAMqAPCRxB3dmw1thc/hls/manifest.m3u8",
		"thumbnail": "https://cdn.api.video/vod/vi1UQBDAMqAPCRxB3dmw1thc/thumbnail.jpg",
		"mp4": "https://cdn.api.video/vod/vi1UQBDAMqAPCRxB3dmw1thc/mp4/1080/source.mp4"
	}
}

This response is sent back immediately. However, the video encoding is unlikely to have completed in the milliseconds it takes to receive this response.

How do I know when the video is ready?

Previously, you would use the video status endpoint which would tell you if the video were playable or not. In several of the demo apps we’ve built, we poll this endpoint every 2-5 seconds to find out when the video ‘isPlayable.’ This is far from ideal.

The Solution: VOD Webhooks

Today we are very happy to announce the launch of VOD webhooks. Now, rather than polling the api to see if the video encoding is completed, your webhook endpoint will receive an alert when each version of a video is ready.

By subscribing to the “video.encoding.quality.completed” webhook, your webhook endpoint will receive a notification when each uploaded video has completed each encoding.

Each response will look something like:

{ 	
	"type": "video.encoding.quality.completed", 
	"emittedAt": "2021-01-29T16:46:25.217+01:00", 
	"videoId": "vi132456789",
	"encoding": "hls", 	
	"quality": "720p" 
}

So, if you are waiting for the mp4, you can filter on encoding to match “mp4”, and then match the videoId, and you’ll know exactly when the file is ready.

When a video is encoded, the first formats to be emitted are typically 240p and 360p. Perhaps you’d want to wait until the 480p or 720p video is ready before displaying the url to your users. Now you can wait until that value arrives at your Webhook, and then make the video urls available to your customers.

Implementation

Using the Create Webhook endpoint, you'll need to subscribe to “video.encoding.quality.completed”, and provide the url of the server that will receive the webhook alerts.

You'll receive a response:

{
  "webhookId": "webhook_123456789",
  "createdAt": "2021-01-08T14:12:18.000+00:00",
	"events": [
		"video.encoding.quality.completed"
	],
	"url": "http://clientnotificationserver.com/notif?myquery=query"
}

Now, whenever a video is encoded with this API key, the webhook endpoint will receive an alert for each version that has been encoded.

Conclusion

We’re really excited to simplify the ways to display video on your websites, and in the next few weeks, we’ll create blogs how we have refactored our sample applications to stop polling on the video status endpoint, and to use the VOD webhook instead.