api.video provides you the possibility to get a POST request to your server that contains a JSON payload with event data. Webhooks can push notifications directly to your server, saving you the need to poll api.video for changes.
Webhook events
Event
Description
live-stream.broadcast.started
Triggers to indicate that a live stream broadcast has started.
live-stream.broadcast.ended
Triggers to indicate that a live stream broadcast has ended.
video.source.recorded
Triggers to indicate that a live stream has been completed and the recording of the live stream (if you set it to record) is ready to be transcoded. NOTE: This means the video has been enqueued for transcoding.
video.encoding.quality.completed
Triggers when you upload a video, every time api.video finishes encoding a video in a set quality (up to the same level of quality that you uploaded), you get an announcement about it.
Here’s how the video.encoding webhook’s flow looks like:
Event properties
api.video offers the following webhook events that you can set up webhooks for:
live-stream.broadcast.started
Triggers to indicate that a live stream broadcast has started.
Property
Type
Description
Example value
type
string
the webhook type
live-stream.broadcast.started
emittedAt
datetime
timestamp when the request was emitted from api.video
2023-05-23T09:29:02.154104779Z
liveStreamId
string
the live stream id
li3VbBGc4e6njqw7fRrELvKl
live-stream.broadcast.ended
Triggers to indicate that a live stream broadcast has ended.
Property
Type
Description
Example value
type
string
the webhook type
live-stream.broadcast.ended
emittedAt
datetime
timestamp when the request was emitted from api.video
2023-05-23T09:29:02.154104779Z
liveStreamId
string
the live stream id
li3VbBGc4e6njqw7fRrELvKl
video.source.recorded
Triggers to indicate that a live stream has completed and the recording of the live stream (if you set it to record) is ready to be transcoded. NOTE: This means the video has been enqueued for transcoding.
Property
Type
Description
Example value
type
string
the webhook type
video.source.recorded
emittedAt
datetime
timestamp when the request was emitted from api.video
2023-05-23T09:29:02.154104779Z
liveStreamId
string
the live stream id
li3VbBGc4e6njqw7fRrELvKl
videoId
string
the video id of the recorded stream
viXXXXXXXX
video.encoding.quality.completed
Triggers when you upload a video, every time api.video finishes encoding a video in a set quality (up to the same level of quality that you uploaded), you get an announcement about it.
Property
Type
Description
Example value
type
string
the webhook type
video.encoding.quality.completed
emittedAt
datetime
timestamp when the request was emitted from api.video
2023-05-23T09:29:02.154104779Z
videoId
string
The ID of the video that was encoded.
viXXXXXXXX
encoding
string
The asset that the encoding was finished for. There are two types of assets that you will receive in the encoding: - HLS - MP4
hls
quality
string
The quality of the video was transcoded to the current encoding.
The MP4 asset will only be transcoded once, hence you will receive a webhook only once for the MP4 asset with the final source quality. While the HLS asset webhook will be emitted multiple times with each quality (from the lowest 240p) to the highest of the source (up to 4k).
For example, if you've uploaded a video where the source quality is 720p. You will receive 5 webhooks in total:
- 1 webhook with 720p quality for the MP4 encoding - 4 webhooks for 240p, 360p, 480p and 720p for the HLS encoding
1080p
Implementation
Testing
You can test your webhooks with tools like Pipedream. These tools enable you to test that api.video sends the correct webhook events, and ensure that webhooks arrive to your server.
Retry policy
Webhook retry policy
api.video’s webhook service makes 3 notification attempts, with 3 second intervals between each try.
Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key.
Create a webhook
To create a webhook, all you have to do is set up your server and provide api.video with the URL you want events sent to and the list of events you wish to be sent to that URL.
List all webhooks
After you create webhooks, you can retrieve a complete list of the URLs and associated events going to them with this code sample:
Show a webhook
You can retrieve details about a specific webhook, including the URL and associated events, by sending a request with the unique webhook ID using this code sample:
Delete a webhook
You can delete a webhook using its unique ID with this code sample:
Warning
Deleting a webhook is a permanent action and deleted webhooks cannot be recovered.
Next steps
You can also use the Get video status endpoint operation to check whether a video is uploaded and ready for playback.
Visit the API reference for a complete list of webhook endpoint operations.