Webhooks

Register and manage webhook endpoints to receive real-time notifications from HeyGen.

Instead of polling GET /v3/videos/{video_id} for status, you can register a webhook endpoint to receive a POST notification when a video completes, fails, or other events occur.

• Base path: https://api.heygen.com/v3/webhooks/endpoints

Authentication

Header	Value
X-Api-Key	Your HeyGen API key
Authorization	Bearer YOUR_ACCESS_TOKEN (OAuth)

Create an Endpoint

Register a URL to receive webhook events. The response includes a secret for verifying payloads — store it securely, as it will not be shown again.

curl

curl -X POST "https://api.heygen.com/v3/webhooks/endpoints" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/heygen",
    "events": ["avatar_video.success", "avatar_video.fail"]
  }'

Request Parameters

Parameter	Type	Required	Description
url	string	Yes	Publicly accessible HTTPS URL that will receive webhook POST requests.
events	array	No	Event types to subscribe to. Omit or set to null to receive all events. See Webhook Events for the full list.
entity_id	string	No	Scope this endpoint to a specific resource (e.g. a personalized video project).

List Endpoints

curl

curl -X GET "https://api.heygen.com/v3/webhooks/endpoints?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Parameter	Type	Required	Default	Description
limit	integer	No	10	Results per page (1–100).
token	string	No	—	Opaque cursor for the next page.

The secret field is only returned when creating an endpoint or rotating the secret. It will be null in list responses.

Update an Endpoint

Change the URL and/or subscribed event types. The events array is fully replaced — include all event types you want to keep.

curl

curl -X PATCH "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/heygen-v2",
    "events": ["avatar_video.success", "avatar_video.fail", "video_agent.success"]
  }'

Both fields are optional — include only what you want to change.

Delete an Endpoint

Permanently remove an endpoint. Events will no longer be delivered to this URL.

curl

curl -X DELETE "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Rotate Signing Secret

Generate a new signing secret for an endpoint. The old secret is immediately invalidated. Store the new secret securely — it will not be shown again.

curl

curl -X POST "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123/rotate-secret" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Verifying Payloads

When HeyGen delivers an event, use the secret from endpoint creation (or rotation) to verify the request is authentic. Compare the signature in the incoming request headers against an HMAC-SHA256 digest of the raw payload body using your secret.

Using Callbacks Instead

If you don’t need a persistent webhook endpoint, you can pass a callback_url directly when creating a video. This sends a one-off notification for that specific video without registering an endpoint:

{
  "prompt": "A product demo for our new app",
  "callback_url": "https://yourapp.com/callbacks/heygen",
  "callback_id": "my-custom-id-123"
}

The callback_id is echoed back in the webhook payload so you can correlate the notification with your request.