> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/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.

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

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

## 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](){/* TODO: update link */}, 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.