Webhook Events

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"

{
  "data": [
    { "event_type": "avatar_video.success", "description": "Fired when an avatar video completes successfully." },
    { "event_type": "avatar_video.fail", "description": "Fired when an avatar video generation fails." },
    { "event_type": "video_agent.success", "description": "Fired when a Video Agent session completes successfully." },
    { "event_type": "video_agent.fail", "description": "Fired when a Video Agent session fails." }
  ],
  "has_more": false,
  "next_token": null
}

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.

Other event types

For other event types, treat the webhook as a completion signal and fetch the authoritative resource state from the API — the detail endpoints return the full, current set of fields for each resource:

Event family	Fetch the result from
`avatar_video.`, `avatar_video_caption.`	`GET /v3/videos/{video_id}`
`video_agent.*`	`GET /v3/video-agents/{session_id}` and `GET /v3/video-agents/{session_id}/videos`
`video_translate.*`	`GET /v3/video-translations/{video_translation_id}`
`photo_avatar_`, `instant_avatar.`	`GET /v3/avatars/looks/{look_id}`

Fetching the video resource also lets you pick exactly the artifact you need — each completed video exposes video_url (the rendered video, with captions burned in only when you requested a caption style), captioned_video_url (the captioned render), subtitle_url (the SRT sidecar file), thumbnail_url, and gif_url. If a webhook hands you a URL with captions you didn’t want, download video_url from GET /v3/videos/{video_id} instead.

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"

{
  "data": [
    {
      "event_id": "evt_abc123",
      "event_type": "avatar_video.success",
      "event_data": {
        "video_id": "vid_xyz789",
        "url": "https://files.heygen.com/video/vid_xyz789.mp4",
        "gif_download_url": "https://resource.heygen.ai/video/vid_xyz789/gif.gif",
        "video_page_url": "https://app.heygen.com/videos/vid_xyz789",
        "video_share_page_url": "https://app.heygen.com/share/vid_xyz789",
        "folder_id": null,
        "callback_id": null
      },
      "created_at": "2026-03-25T12:05:00Z"
    }
  ],
  "has_more": false,
  "next_token": null
}

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"
  ]
}

{
  "url": "https://yourapp.com/webhooks/heygen"
}

Omitting the 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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Authentication

Event Types

Available Event Types

Event Data Payloads

`avatar_video.success`

Other event types

List Delivered Events

Query Parameters

Response Fields

Subscribing to Events

Handling Events in Your Application

​Authentication

​Event Types

​Available Event Types

​Event Data Payloads

​avatar_video.success

​Other event types

​List Delivered Events

​Query Parameters

​Response Fields

​Subscribing to Events

​Handling Events in Your Application

Authentication

Event Types

Available Event Types

Event Data Payloads

`avatar_video.success`

Other event types

List Delivered Events

Query Parameters

Response Fields

Subscribing to Events

Handling Events in Your Application