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.
Before receiving video related events, you need to configure webhooks in your ImageKit account.
video.transformation.acceptedvideo.transformation.readyvideo.transformation.error
video.transformation.accepted
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 the 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 the 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. |
video.transformation.ready
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 th submitted request. |
| request.x_request_id | A unique request ID to identify request. |
| request.user_agent | user_agent in the submitted request. |
| data.asset.url | URL to download the 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. |
video.transformation.error
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. For the any other error reason, raise a support ticket at support@imagekit.io.
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 the submitted request. |
| request.x_request_id | A unique request ID to identify request. |
| request.user_agent | user_agent in the submitted request. |
| data.asset.url | URL to download the 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. |