Webhook Events

Understand the event types HeyGen can deliver and browse your event history.

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:

curl

curl -X GET "https://api.heygen.com/v3/webhooks/event-types" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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.

List Delivered Events

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

curl

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

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