Video webhooks events
Listen to video webhooks events for setting up an end-to-end video encoding pipeline using ImageKit Video API.
Use webhook to get real-time updates about video transformation operations. Use the events like
video.transformation.accepted and video.transformation.ready to automatically update fields in your database or CMS.video.transformation.acceptedvideo.transformation.readyvideo.transformation.error
It is triggered when a new video transformation request is accepted for processing. You can use this for debugging purposes.
Example payload looks like below:
{
"type": "video.transformation.accepted",
"id": "58e6d24d-6098-4319-be8d-40c3cb0a402d",
"created_at": "2022-06-20T11:59:58.461Z",
"request": {
"x_request_id": "fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9",
"url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
},
"data": {
"asset": {
"url": "http://ik.imagekit.io/demo/sample-video.mp4"
},
"transformation": {
"type": "video-transformation",
"options": {
"video_codec": "vp9",
"audio_codec": "opus",
"auto_rotate": true,
"quality": 10,
"format": "webm"
}
}
}
}
Here is the description of all fields.
Field | Description |
|---|---|
type | Type of event. |
id | Unique identifier of the event. |
createdAt | Timestamp of the event in ISO8601 format. |
request.url | URL of submitted request. |
request.x_request_id | A unique request id to identify request. |
request.user_agent | user_agent in submitted request. |
data.asset.url | URL to download source video file. |
data.transformation.type | video-transformation, gif-to-video, video-thumbnail |
data.transformation.options.video_codec | h264 or vp9 |
data.transformation.options.audio_codec | aac or opus |
data.transformation.options.format | mp4, webm, jpg, png or webp |
data.transformation.options.stream_protocol | HLS or DASH |
data.transformation.options.variants | Array of representations for ABS e.g. ["360","480","720","1028"]. |
data.transformation.options.auto_rotate | A boolean indicating whether to autorotate the video based on their metadata. |
It is triggered when a video encoding is finished, and the transformed resource is ready to be served. You should listen to this webhook and update any flag in your database or CMS against that particular asset so your application can start showing it to users.
Example payload looks like below:
{
"type": "video.transformation.ready",
"id": "a03031b5-ad5f-4985-8cf5-4de67630f6d7",
"created_at": "2022-06-20T12:00:11.703Z",
"request": {
"x_request_id": "fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9",
"url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
},
"timings": {
"download_duration": 2713,
"encoding_duration": 10175
},
"data": {
"asset": {
"url": "http://ik.imagekit.io/demo/sample-video.mp4"
},
"transformation": {
"type": "video-transformation",
"options": {
"video_codec": "vp9",
"audio_codec": "opus",
"auto_rotate": true,
"quality": 10,
"format": "webm"
},
"output": {
"url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
"video_metadata": {
"duration": 15.023,
"width": 1280,
"height": 720,
"bitrate": 180260
}
}
}
}
}
Here is the description of all fields.
Field | Description |
|---|---|
type | Type of event. |
id | Unique identifier of the event. |
createdAt | Timestamp of the event in ISO8601 format. |
request.url | URL of submitted request. |
request.x_request_id | A unique request id to identify request. |
request.user_agent | user_agent in submitted request. |
data.asset.url | URL to download source video file. |
data.transformation.type | video-transformation, gif-to-video, video-thumbnail |
data.transformation.options.video_codec | h264 or vp9 |
data.transformation.options.audio_codec | aac or opus |
data.transformation.options.format | mp4, webm, jpg, png or webp |
data.transformation.options.stream_protocol | HLS or DASH |
data.transformation.options.variants | Array of representations for ABS e.g. ["360","480","720","1028"]. |
data.transformation.options.auto_rotate | A boolean indicating whether to autorotate the video based on their metadata. |
data.transformation.output.video_metadata.duration | Output duration in seconds. |
data.transformation.output.video_metadata.bitrate | Output bitrate (bits/second). |
data.transformation.output.video_metadata.width | Output video width. |
data.transformation.output.video_metadata.height | Output video height. |
data.transformation.output.url | URL to download output video. |
data.timings.download_duration | Time spent downloading the video from your origin or media library in milliseconds. |
data.timings.encoding_duration | Time spent in encoding in milliseconds. |
It is triggered if an error occurs during encoding. Listen to this webhook to log the reason. You should check your origin and URL-endpoint settings if the reason is related to download failure. If the reason seems like an error on the ImageKit side, then raise a support ticket at [email protected]
Example payload looks like below:
{
"type": "video.transformation.error",
"request": {
"x_request_id": "f005b939-7ca3-4310-9e1e-009239b3616b",
"url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-nonexistent.png,l-end",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
},
"id": "293a65c6-ceb4-4b62-a10b-5f3333860fae",
"created_at": "2022-06-20T12:14:02.353Z",
"data": {
"asset": {
"url": "http://ik.imagekit.io/demo/sample-video.mp4"
},
"transformation": {
"type": "video-transformation",
"options": {
"video_codec": "vp9",
"audio_codec": "opus",
"auto_rotate": true,
"quality": 50,
"format": "webm"
},
"error": {
"reason": "download_failed"
}
}
}
}
Here is the description of all fields.
Field | Description |
|---|---|
type | Type of event. |
id | Unique identifier of the event. |
createdAt | Timestamp of the event in ISO8601 format. |
request.url | URL of submitted request. |
request.x_request_id | A unique request id to identify request. |
request.user_agent | user_agent in submitted request. |
data.asset.url | URL to download source video file. |
data.transformation.type | video-transformation, gif-to-video, video-thumbnail |
data.transformation.options.video_codec | h264 or vp9 |
data.transformation.options.audio_codec | aac or opus |
data.transformation.options.format | mp4, webm, jpg, png or webp |
data.transformation.options.stream_protocol | HLS or DASH |
data.transformation.options.variants | Array of representations for ABS e.g. ["360","480","720","1028"]. |
data.transformation.options.auto_rotate | A boolean indicating whether to autorotate the video based on their metadata. |
data.transformation.error.reason | One of encoding_failed, download_failed, internal_server_error. |
Last modified 6mo ago