Skip to main content
POST
Create Webhook Endpoint

Authorizations

x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request body for POST /v3/webhooks/endpoints.

url
string
required

Publicly accessible HTTPS URL that will receive webhook POST requests.

events
enum<string>[] | null

Event types to subscribe to. Omit or set to null to receive all events.

Available options:
avatar_video.success,
avatar_video.fail,
avatar_video_gif.success,
avatar_video_gif.fail,
video_translate.success,
video_translate.fail,
video_translate.preflight.validation_failed,
video_translate.preflight.download_failed,
personalized_video,
instant_avatar.success,
instant_avatar.fail,
photo_avatar_generation.success,
photo_avatar_generation.fail,
photo_avatar_train.success,
photo_avatar_train.fail,
photo_avatar_add_motion.success,
photo_avatar_add_motion.fail,
proofread_creation.success,
proofread_creation.fail,
live_avatar.success,
live_avatar.fail,
avatar_video_caption.success,
avatar_video_caption.fail,
video_agent.success,
video_agent.fail,
hyperframes_video.success,
hyperframes_video.fail,
ai_clipping.success,
ai_clipping.fail,
filler_word_removal.success,
filler_word_removal.fail,
podcast.success,
podcast.fail,
batch.finished
entity_id
string | null

Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project).

Response

Successful response

data
WebhookEndpointResponse · object

A registered webhook endpoint.