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 -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 -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 -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"]
}'
Delete an Endpoint
Permanently remove an endpoint. Events will no longer be delivered to this URL.
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 -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"
}
callback_id is echoed back in the webhook payload so you can correlate the notification with your request. 
