Video webhooks events

Webhook support for video
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 webhook events
video.transformation.accepted
video.transformation.ready
video.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 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.
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 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.
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. 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.

Adaptive bitrate streaming

Next - ✨Features

Video Optimization

Last modified 2mo ago

Copy link

On this page

Webhook support for video

Video webhook events

video.transformation.accepted

video.transformation.ready

video.transformation.error