Webhook events are how the HeyGen notifies your endpoints when a variety of interactions or events happen, including when avatar video processing succeeds or fails. Webhook events are sent by HeyGen as POST requests to your webhook endpoint.

Getting Started

List Available Webhooks Events

See detailed API reference
Let's quickly get started with webhooks by listing all available webhook events in HeyGen API.

curl --request GET \
     --url https://api.heygen.com/v1/webhook/webhook.list \
     --header 'accept: application/json' \
     --header 'x-api-key: <your-api-key>'

{
  "code": 100,
  "data": [
    "avatar_video.success",
    "avatar_video.fail",
    "avatar_video_gif.success",
    "avatar_video_gif.fail",
    "video_translate.success",
    "video_translate.fail",
    "personalized_video"
  ],
  "msg": null,
  "message": null
}

Basically, HeyGen can make requests to your endpoint when 'Video succeeds' and 'Video fails'.

Payloads Your Endpoint Will Receive

Your endpoint receive following payloads:

{
  "event_type": "avatar_video.success",
  "event_data": {
    "video_id": "<video_id>",
    "url": "<video-url>",
    "callback_id": "<callback_id>"
  }
}

{
  "event_type": "avatar_video.fail",
  "event_data": {
    "video_id": "<video_id>",
    "msg": "<failure-message>",
    "callback_id": "<callback_id>"
  }
}

{
  "event_type": "video_translate.success",
  "event_data": {
    "video_translate_id": "<video_translate_id>",
    "url": "<video-url>",
    "callback_id": "<callback-id>",
    "output_language": "<output-language>"
  }
}

{
  "event_type": "video_translate.fail",
  "event_data": {
    "video_translate_id": "<video_translate_id>",
    "message": "<failure-message>",
    "callback_id": "<callback-id>",
    "output_language": "<output-language>"
  }
}

{
  "event_type": "personalized_video",
  "event_data": {
    "project_id": "<project_id>",
    "video_id": "<video_id>",
    "video_url": "<video_url>",
    "landing_page_url": "<landing_page_url>",
    "gif_url": "<gif_url>",
    "gif_html": "<gif_html>",
    "contact_info": "<contact_info>"
  }
}

avatar_video_gif payload is the same as avatar_video.

Register a Webhook Endpoint

See detailed API reference
Use add a webhook endpoint to register your endpoint which is used to process HeyGen events. events are the events you want to process.

curl --location 'https://api.heygen.com/v1/webhook/endpoint.add' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data '
{
  "url": "<your-endpoint>",
  "events": ["avatar_video.success"]
}'

{
  "code": 100,
  "data": {
    "endpoint_id": "<endpoint_id>",
    "username": "<username>",
    "url": "<your-endpoint>",
    "status": "enabled",
    "events": ["avatar_video.success"],
    "secret": "<secret>",
    "created_at": "2023-06-28T13:34:51.293528",
    "space_id": "<space_id>"
  },
  "msg": null,
  "message": null
}

List Registered Webhook Endpoints

See detailed API reference
You can use this endpoint to list your registered endpoints.

curl -XGET https://api.heygen.com/v1/webhook/endpoint.list
     -H 'Accept: application/json'
     -H 'X-Api-Key: <your-api-key>'

{
  "code": 100,
  "data": [
    {
      "username": "<username>",
      "status": "enabled",
      "events": ["avatar_video.success"],
      "created_at": "2023-10-17T19:47:31",
      "url": "<your-webhook-endpoint>",
      "endpoint_id": "<endpoint_id>",
      "secret": "<secret>",
      "space_id": "<space_id>"
    }
  ],
  "msg": null,
  "message": null
}

Update a Registered Webhook Endpoint

See detailed API reference
Use update a webhook endpoint to update the information of a registered endpoint.

curl -XPATCH https://api.heygen.com/v1/webhook/endpoint.update
     -H 'Content-Type: application/json'
     -H 'X-Api-Key: <your-api-key>'
     -d '
{
  "endpoint_id": "<endpoint_id>",
  "url": "<updated-url>",
  "events": ["avatar_video.fail"]
}'

{
  "code": 100,
  "data": {
    "endpoint_id": "<endpoint_id>",
    "username": "<username>",
    "url": "<updated-url>",
    "status": "enabled",
    "events": ["avatar_video.fail"],
    "secret": "<secret>",
    "created_at": "2023-06-28T13:34:51.293528",
    "space_id": "<space_id>"
  },
  "msg": null,
  "message": null
}

Delete a Registered Webhook Endpoint

See detailed API reference
Use delete a webhook endpoint to delete a registered endpoint.

curl --location --request DELETE 'https://api.heygen.com/v1/webhook/endpoint.delete?endpoint_id=<endpoint_id>' \
--header 'accept: application/json' \
--header 'X-Api-Key: <your-api-key>'

{
  "code": 100,
  "data": null,
  "msg": null,
  "message": null
}

Let's Build Our Own Endpoint App

We will create a simple endpoint with Python and Flask, then we will expose this local webhook endpoint to the internet, then we will register it to HeyGen webhook events and start receiving video information to our endpoint. Follow up! 🙌

Write Your Endpoint To Process Webhook Events

Conclusion

HeyGen's webhook events and APIs provide essential tools for managing avatar video generation. With options to register, update, and process events you can effortlessly stay informed about the status of your avatar videos. Whether you want to handle successful video generation or address any issues that may arise, HeyGen's webhook system keeps you in the loop.