# Add a Webhook Endpoint
Registers a webhook endpoint to receive real-time event notifications from HeyGen.
**Note:**
* During validation, HeyGen sends an `OPTIONS` request to your endpoint with a 1-second timeout. Ensure your server responds quickly and accepts `OPTIONS` requests, even if your main webhook logic uses different HTTP methods.
* Scroll down to the **Responses** section below and expand the status code(s) to view the detailed response schema.
* Refer to the **RESPONSE** section on the right and choose an example to see how the API response appears for each status code.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "heygen-api",
"version": "4.0.8"
},
"servers": [
{
"url": "https://api.heygen.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/v1/webhook/endpoint.add": {
"post": {
"summary": "Add a Webhook Endpoint",
"description": "Set up webhooks for real-time event notifications and automate your workflow",
"operationId": "add-a-webhook-endpoint",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL where HeyGen will send event notifications. _Only servers with SSL security level 2 or above are supported._ To create a webhook endpoint URL, refer to the Write Your Endpoint To Process Webhook Events guide. "
},
"events": {
"type": "array",
"description": "A list of event types your webhook should listen to. If not specified or left `null`, the webhook will be configured to receive all available events. To view supported event types, refer to the [List Available Webhook Events](https://docs.heygen.com/reference/list-available-webhook-events) endpoint.",
"items": {
"type": "string"
}
},
"entity_id": {
"type": "string",
"description": "The specific entity ID associated with the webhook, for example, `video_id`, `project_id`, etc. **Note:** This field is only applicable to translated videos with multiple language versions. "
}
},
"required": [
"url"
]
}
}
}
},
"responses": {
"200": {
"description": "Webhook endpoint added successfully - Expand to view the detailed response schema.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": {
"code": 100,
"data": {
"username": "15ezy7d83a8541f0b8d56a14c8a4db72",
"url": "https://smee.io/TqmiZula18yuKuUV",
"events": null,
"secret": "drfec_TS_ZwqJ-HujBO0KvEMqxrg==",
"space_id": "05gbafd53a7541f0b8d56c14c8a4ca75",
"entity_id": null,
"endpoint_id": "ac107bc9f1b344ad9384f93458e236f0",
"status": "enabled",
"created_at": "2025-10-21T13:49:18.054068"
},
"msg": null,
"message": null
}
}
},
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 100,
"default": 0,
"description": "Status code indicating the result of the API request. A 100 indicates a successful response. Other codes might indicate different types of errors. Refer to the Error Responses for more details."
},
"data": {
"type": "object",
"properties": {
"username": {
"type": "string",
"example": "123456",
"description": "Unique identifier of the user who registered the webhook endpoint."
},
"url": {
"type": "string",
"example": "https://helloworld.com",
"description": "Callback URL where Heygen delivers event notifications."
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of specific event types the endpoint is subscribed to. A `null` value means the endpoint listens to all events."
},
"secret": {
"type": "string",
"example": "whsec_123456",
"description": "Secret key associated with the endpoint. Used to verify that webhook requests originate from HeyGen."
},
"space_id": {
"type": "string",
"description": "Unique identifier of the space or environment the webhook endpoint belongs to. "
},
"entity_id": {
"type": "string",
"description": "Identifier associated with a specific entity, if applicable. May return `null` if not linked to any entity. "
},
"endpoint_id": {
"type": "string",
"example": "038fb5f9a62d48e5af08834d20404606",
"description": "Unique identifier of the registered webhook endpoint. "
},
"status": {
"type": "string",
"example": "enabled",
"description": "Indicates whether the endpoint is currently active or inactive. ",
"enum": [
"enabled",
"disabled"
]
},
"created_at": {
"type": "string",
"example": "2023-04-03T05:40:46.769845",
"description": "The date and time when the endpoint was registered. ",
"format": "date-time"
}
},
"description": "Contains information about the registered endpoint. "
},
"msg": {
"type": "string",
"description": "Legacy field for messages. This field is deprecated."
},
"message": {
"type": "string",
"description": "New field for messages. Contains human-readable messages explaining the status of the request. In case of errors, it returns an explanation."
}
}
}
}
}
},
"400": {
"description": "Invalid URL",
"content": {
"application/json": {
"examples": {
"Invalid URL": {
"value": "{\"code\":400542,\"message\":\"Url of this webhook endpoint is invalid\"}",
"summary": "Invalid URL"
}
},
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 400542,
"default": 0
},
"message": {
"type": "string",
"example": "Url of this webhook endpoint is invalid"
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```