Documentation Index
Fetch the complete documentation index at: https://developers.heygen.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
