---
title: "Create Webhook Endpoint"
method: POST
path: "/v3/webhooks/endpoints"
tags: ["Webhooks"]
---

# Create Webhook Endpoint

`POST /v3/webhooks/endpoints`

Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation — store it securely.

## Headers

- `Idempotency-Key` string

## Request body

- CreateWebhookEndpointRequest — Request body for POST /v3/webhooks/endpoints.
  - `url` string, required — Publicly accessible HTTPS URL that will receive webhook POST requests.
  - `events` WebhookEventType[], nullable — Event types to subscribe to. Omit or set to null to receive all events.
  - `entity_id` string, nullable — Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project).

## Response `200`

Successful response

- object
  - `data` WebhookEndpointResponse — A registered webhook endpoint.
    - `endpoint_id` string, required — Unique identifier for this webhook endpoint.
    - `url` string, required — The URL that receives webhook POST requests.
    - `events` string[], nullable — Event types this endpoint subscribes to. Null means all events.
    - `status` string, required — Endpoint status: 'enabled' or 'disabled'.
    - `created_at` string, required — ISO 8601 timestamp when the endpoint was created.
    - `secret` string, nullable — The signing secret for verifying webhook payloads. Only returned on create and rotate-secret.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `409` — Conflict — either the request conflicts with existing state, or a prior request with this `Idempotency-Key` is still in progress (`request_in_progress`).
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/versions/e2e54726e210/schema)