Create And Manage Webhooks
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.
Choose an api.video client
The clients offered by api.video include:
To install your selected client, do the following:
Create an account
Before you can start creating webhooks, you need to create an api.video account.
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.
Was this page helpful?