> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Reference every HeyGen webhook event type, such as avatar_video.success, video_agent.fail and video_translate.success, with the avatar_video.success payload and where to fetch results for the rest.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-1.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=75889d32f3d54871cdb75d24c86b82da)

HeyGen sends webhook events as POST requests to your registered endpoints. This page covers the available event types and how to browse delivered events.

## Event Types

[`GET /v3/webhooks/event-types`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-event-types) returns every supported `event_type` with its `description`, authenticated with your `X-Api-Key` like the rest of the API.

### 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. |
| `hyperframes_video.success` | HyperFrames render completed. |
| `hyperframes_video.fail` | HyperFrames render failed. |
| `ai_clipping.success` | AI Clipping job completed. |
| `ai_clipping.fail` | AI Clipping job failed. |
| `filler_word_removal.success` | Filler word removal completed. |
| `filler_word_removal.fail` | Filler word removal failed. |
| `video_translate.preflight.validation_failed` | Video translation stopped before processing: the source video failed validation. |
| `video_translate.preflight.download_failed` | Video translation stopped before processing: the source video could not be downloaded. |
| `batch.finished` | Every item in a [batch](https://heygen-1fa696a7.mintlify.site/batch-videos.md) reached a terminal state. |

Digital twins use the `instant_avatar.*` events. Photo avatars use the `photo_avatar_*` events.

## 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`. |

> [!NOTE]
>
> 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}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) |
| `video_agent.*` | [`GET /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-agent-session) and [`GET /v3/video-agents/{session_id}/videos`](https://heygen-1fa696a7.mintlify.site/reference/list-session-videos) |
| `video_translate.*` | [`GET /v3/video-translations/{video_translation_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-translation) |
| `photo_avatar_*`, `instant_avatar.*` | [`GET /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look) |
| `hyperframes_video.*` | [`GET /v3/hyperframes/renders/{render_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-hyperframes-render) |
| `ai_clipping.*` | [`GET /v3/ai-clipping/{job_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-ai-clipping) |
| `filler_word_removal.*` | [`GET /v3/filler-word-removals/{filler_word_removal_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-filler-word-removal) |

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}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) instead.

## List Delivered Events

Browse events that have been delivered to your endpoints with [`GET /v3/webhooks/events`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-events). Filter by `event_type` or `entity_id` (e.g. a video ID or session ID), and page with `limit` (1–100, default `10`) and `token`.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/webhooks/events?event_type=avatar_video.success&limit=5" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

Each event in `data` has an `event_id` (unique per delivery), `event_type`, `event_data` (the payload, whose contents vary by event type), and an ISO 8601 `created_at`.

## Subscribing to Events

Pass the event types you want in the `events` array when [creating a webhook endpoint](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md#create-an-endpoint), or omit `events` (or set it to `null`) to subscribe 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

HeyGen sends a POST request to your endpoint URL with the event payload as JSON. A typical handler:

1. **Verify the signature** using your endpoint's signing secret, as shown in [Verifying Payloads](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md#verifying-payloads).
2. **Parse `event_type`** to determine what happened.
3. **Process `event_data`**: the `avatar_video.success` fields listed above, or error details for failures.
4. **Return a 2xx response** promptly to acknowledge receipt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.