​
Event format

All webhook events are in the following format:

{
  "type": "<event name>",
  "payload": {
    ...
  }
}

​
Video events

The payload matches the response of GET /v1/video-projects/:id.

The example payload includes the subset of fields to pay attention to.

​
video.started

This event is triggered when rendered begins.

"status": "rendering",
"downloads": [],
"error": null

​
video.completed

This event is triggered when video is completed. The payload includes the link to download the video file.

"status": "complete",
"downloads": [
    {
        "url": "https://video.magichour.ai/id/output.mp4?auth-token=1234",
        "expires_at": "2024-10-19T05:16:19.027Z"
    }
],
"error": null

​
video.errored

This event is triggered when the video ran into an error. The payload includes details on the error

"status": "error",
"downloads": [],
"error": {
    "code": "invalid_video_file",
    "message": "The video file contains invalid data. Please try a different file.",
},
In case of errors, you are not charged for any usage

​
Image events

The payload matches the response of GET /v1/image-projects/:id

​
image.started

This event is triggered when rendering begins.

"status": "rendering",
"downloads": [],
"error": null
Some modes do not send image.started due to fast renders.

​
image.completed

This event is triggered when image is completed. The payload includes the link to download the video file.

"status": "complete",
"downloads": [
    {
        "url": "https://video.magichour.ai/id/output.png",
        "expires_at": "2024-10-19T05:16:19.027Z"
    }
],
"error": null

​
image.errored

This event is triggered when the image ran into an error.

"status": "error",
"downloads": [],
"error": {
    "code": "no_source_face",
    "message": "Please use an image with a detectable face"
},
In case of errors, you are not charged for any usage

Was this page helpful?

Securing HandlerBilling Overview