Live stream webhooks: We'll tell you when the stream starts

When your application is managing a number of live streams (or live streamers), it might be tricky to keep tabs on which streams are live at any given time. The List all livestreams endpoint will give a list of the streams, and you could parse the broadcasting attribute: true - the stream is live: false - the stream is not live.

But polling an endpoint is less than optimal, so we have just released new webhooks that will push this information to your server. The 2 new webhooks for live streaming status are:

1. live-stream.broadcast.started A livestream has begun broadcasting. The body of the message will look like:

{
	"type": "live-stream.broadcast.started",
	"emittedAt": "2021-01-29T16:46:25.217+01:00",
	"liveStreamId": "liXXXXXXXX"
}

This data says - hey this livetream with liveStreamId "lixxxxxxx" has began broadcasting - you can now perform tasks to make this live stream visible.  

Note: This webhook fires when the broadcast has just started. It will take a few seconds for the video to become encoded and be available for playback for your viewers. If you use the api.video player url, the player will refresh for 20s, giving plenty of time for the livestream to establish streaming and appear to your viewer.

2. live-stream.broadcast.ended Like all good things, a livestream will eventually end. This webhook will fire when the last bit of video has been encoded (typically a few seconds after the streamer has actually stopped streaming). The body of this message looks like:

{
	"type": "live-stream.broadcast.ended",
  "emittedAt": "2021-01-29T16:46:25.217+01:00",
	"liveStreamId": "liXXXXXXXX"
}

Now your application logic can remove this stream from your users.

Creating a Live Webhook

Using the Create Webhook endpoint, you can establish the URL where the webhooks will be sent. Here is an example using curl:

 curl --request POST  --url https://ws.api.video/webhooks   --header 'accept: application/vnd.api.video+json'  --header 'authorization: Bearer <api_token here>' --data '{"events": [
		"live-stream.broadcast.started", "live-stream.broadcast.ended", "video.encoding.quality.completed"
	], "url": "https://webhook.a.video/receive_webhook"
}'

https://webhook.a.video/receive_webhook is the url that will get the updates on live streaming (and also on video encoding quality). If you guessed that https://webhook.a.video has a demo showcasing these webhooks, you'd be correct. To start a livestream - visit record.a.video or livestream.a.video, and start a livestream. You'll see the webhook alert that the livestream has started at the bottom of the list. When you end your livestream, you'll see the ended notification a few seconds after you stopped (after all of the video has been processed). As the video is recorded into VOD, you'll also see the quality encoding completed alerts. (read more about the quality.encoded webhook).

Other Livestream Webhooks

We have 2 additional features in our webhooks that help simplify live stream management - mainly if you record your livestreams for video on demand playback.

1. video.source.recorded The live stream has completed, and the recording is ready to be transcoded. Note: this does not tell you that the recording is ready for playback, only that recording/transcoding is starting, and the videoId where the recording of the livestream will be stored. The webhook message appears as:

{
	"type": "video.source.recorded",
  "emittedAt": "2021-01-29T16:46:25.217+01:00",
	"liveStreamId": "liXXXXXXXX",
  "videoId": "viXXXXXXXX"
}

2. video.encoding.quality.completed - our VOD webhook - now lists the liveStreamId in the response (if the video's source is a live stream). This webhook notification will tell you when each VOD quality has been encoded. You'll get the videoId (as before), but if the video is a recorded live stream, you'll also get the liveStreamId:

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

Conclusion

We're very excited about our new live streaming webhooks - we've had several customers ask for them over the last few months, and we know it will make the managment of multiple live streams a lot easier. If you are using our webhooks for your livestream management - drop us a note on our community page and let us know how they work for you.