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.

​
Authentication

HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
Event Types

Fetch the full list of supported event types and their descriptions: 
curl -X GET "https://api.heygen.com/v3/webhooks/event-types" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Available Event Types

Event TypeDescription
avatar_video.successAvatar video completed successfully.
avatar_video.failAvatar video generation failed.
avatar_video_gif.successAvatar video GIF generation completed.
avatar_video_gif.failAvatar video GIF generation failed.
avatar_video_caption.successAvatar video caption generation completed.
avatar_video_caption.failAvatar video caption generation failed.
video_translate.successVideo translation completed.
video_translate.failVideo translation failed.
video_agent.successVideo Agent session completed.
video_agent.failVideo Agent session failed.
personalized_videoPersonalized video event.
instant_avatar.successInstant avatar creation completed.
instant_avatar.failInstant avatar creation failed.
photo_avatar_generation.successPhoto avatar generation completed.
photo_avatar_generation.failPhoto avatar generation failed.
photo_avatar_train.successPhoto avatar training completed.
photo_avatar_train.failPhoto avatar training failed.
photo_avatar_add_motion.successPhoto avatar motion addition completed.
photo_avatar_add_motion.failPhoto avatar motion addition failed.
proofread_creation.successProofread creation completed.
proofread_creation.failProofread creation failed.
live_avatar.successLive avatar session completed.
live_avatar.failLive avatar session failed.

​
List Delivered Events

Browse events that have been delivered to your endpoints. Filter by event type or entity ID. 
curl -X GET "https://api.heygen.com/v3/webhooks/events?event_type=avatar_video.success&limit=5" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Query Parameters

ParameterTypeRequiredDefaultDescription
event_typestringNoallFilter by a specific event type (e.g. "avatar_video.success").
entity_idstringNo—Filter by entity ID (e.g. a video ID or session ID).
limitintegerNo10Results per page (1–100).
tokenstringNo—Opaque cursor for the next page.

​
Response Fields

Each event in the data array contains:
FieldTypeDescription
event_idstringUnique identifier for this event delivery.
event_typestringThe event type (e.g. "avatar_video.success").
event_dataobjectThe event payload. Contents vary by event type.
created_atstringISO 8601 timestamp when the event was created.

​
Subscribing to Events

When creating a webhook endpoint, pass the event types you want to receive in the events array: 
{
  "url": "https://yourapp.com/webhooks/heygen",
  "events": [
    "avatar_video.success",
    "avatar_video.fail",
    "video_agent.success",
    "video_agent.fail"
  ]
}
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 success events this typically includes the video_id and video_url; for failures it includes error details.
  4. Return a 2xx response promptly to acknowledge receipt.