Skip to main content
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 returns every supported event_type with its description, authenticated with your X-Api-Key like the rest of the API.

Available Event Types

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

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: 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 with GET /v3/webhooks/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.
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, 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.
  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.