Video webhooks events

Listen to video webhooks events for setting up an end-to-end video encoding pipeline using ImageKit Video API.

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 [e-mail].

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.