> ## 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 with full payload schemas. Includes video.completed, video.failed, translation.completed, with example JSON.

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-1.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=75889d32f3d54871cdb75d24c86b82da" alt="" noZoom width="1400" height="788" data-path="images/theme/research-1.webp" />

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:

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/webhooks/event-types" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

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

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

<Info>
  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.
</Info>

### 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}`](/reference/get-video) |
| `video_agent.*` | [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) and [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos) |
| `video_translate.*` | [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) |
| `photo_avatar_*`, `instant_avatar.*` | [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) |

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}`](/reference/get-video) instead.

## List Delivered Events

Browse events that have been delivered to your endpoints. Filter by event type or entity ID.

<CodeGroup>
  ```bash curl 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"
  ```

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

### 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](/docs/webhooks#create-an-endpoint), pass the event types you want to receive in the `events` array:

<CodeGroup>
  ```json "Subscribe to video events only" theme={null}
  {
    "url": "https://yourapp.com/webhooks/heygen",
    "events": [
      "avatar_video.success",
      "avatar_video.fail",
      "video_agent.success",
      "video_agent.fail"
    ]
  }
  ```

  ```json "Receive all events" theme={null}
  {
    "url": "https://yourapp.com/webhooks/heygen"
  }
  ```
</CodeGroup>

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:

1. **Verify the signature** using your endpoint's signing secret.
2. **Parse `event_type`** to determine what happened.
3. **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.
4. **Return a 2xx response** promptly to acknowledge receipt.


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