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
Theevent_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 withGET /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.
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 theevents 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:- Verify the signature using your endpoint’s signing secret, as shown in Verifying Payloads.
- Parse
event_typeto determine what happened. - Process
event_data: theavatar_video.successfields listed above, or error details for failures. - Return a 2xx response promptly to acknowledge receipt.

