HeyGen sends webhook events as POST requests to your registered endpoints. This page covers the available event types and how to browse delivered events.
Authentication
| Header | Value |
|---|
X-Api-Key | Your HeyGen API key |
Authorization | Bearer YOUR_ACCESS_TOKEN (OAuth) |
Event Types
Fetch the full list of supported event types and their descriptions:
curl -X GET "https://api.heygen.com/v3/webhooks/event-types" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Available Event Types
| Event Type | Description |
|---|
avatar_video.success | Avatar video completed successfully. |
avatar_video.fail | Avatar video generation failed. |
avatar_video_gif.success | Avatar video GIF generation completed. |
avatar_video_gif.fail | Avatar video GIF generation failed. |
avatar_video_caption.success | Avatar video caption generation completed. |
avatar_video_caption.fail | Avatar video caption generation failed. |
video_translate.success | Video translation completed. |
video_translate.fail | Video translation failed. |
video_agent.success | Video Agent session completed. |
video_agent.fail | Video Agent session failed. |
personalized_video | Personalized video event. |
instant_avatar.success | Instant avatar creation completed. |
instant_avatar.fail | Instant avatar creation failed. |
photo_avatar_generation.success | Photo avatar generation completed. |
photo_avatar_generation.fail | Photo avatar generation failed. |
photo_avatar_train.success | Photo avatar training completed. |
photo_avatar_train.fail | Photo avatar training failed. |
photo_avatar_add_motion.success | Photo avatar motion addition completed. |
photo_avatar_add_motion.fail | Photo avatar motion addition failed. |
proofread_creation.success | Proofread creation completed. |
proofread_creation.fail | Proofread creation failed. |
live_avatar.success | Live avatar session completed. |
live_avatar.fail | Live avatar session failed. |
Event Data Payloads
The event_data shape varies by event type. Below are the fields for avatar_video.success:
avatar_video.success
| Field | Type | Description |
|---|
video_id | string | Unique ID for the completed video. |
url | string | Pre-signed download URL for the video file. |
gif_download_url | string | Pre-signed download URL for the GIF preview. |
video_page_url | string | URL to the video in the HeyGen app. |
video_share_page_url | string | Shareable URL for the video. |
folder_id | string | null | Folder the video belongs to, or null. |
callback_id | string | null | Value of callback_id passed when creating the video, or null. |
The video download URL (url) is a pre-signed URL with a limited expiry window. Fetch and store the file promptly, or re-fetch the URL via GET /v3/videos/{video_id} if it expires.
List Delivered Events
Browse events that have been delivered to your endpoints. Filter by event type or entity ID.
curl -X GET "https://api.heygen.com/v3/webhooks/events?event_type=avatar_video.success&limit=5" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
event_type | string | No | all | Filter by a specific event type (e.g. "avatar_video.success"). |
entity_id | string | No | — | Filter by entity ID (e.g. a video ID or session ID). |
limit | integer | No | 10 | Results per page (1–100). |
token | string | No | — | Opaque cursor for the next page. |
Response Fields
Each event in the data array contains:
| Field | Type | Description |
|---|
event_id | string | Unique identifier for this event delivery. |
event_type | string | The event type (e.g. "avatar_video.success"). |
event_data | object | The event payload. Contents vary by event type. |
created_at | string | ISO 8601 timestamp when the event was created. |
Subscribing to Events
When creating a webhook endpoint, pass the event types you want to receive in the events array:
{
"url": "https://yourapp.com/webhooks/heygen",
"events": [
"avatar_video.success",
"avatar_video.fail",
"video_agent.success",
"video_agent.fail"
]
}
events field (or setting it to null) subscribes the endpoint to all event types.
To change subscriptions later, use PATCH /v3/webhooks/endpoints/{endpoint_id} with an updated events array.
Handling Events in Your Application
When an event is delivered, HeyGen sends a POST request to your endpoint URL with the event payload as JSON. A typical handler:
- Verify the signature using your endpoint’s signing secret.
- Parse
event_type to determine what happened.
- Process
event_data — for avatar_video.success events this includes video_id, url (the video download URL), gif_download_url, video_page_url, video_share_page_url, folder_id, and callback_id; for failures it includes error details.
- Return a 2xx response promptly to acknowledge receipt.
