HEheygen
Webhooks

Create Webhook Endpoint

Changed on

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.

post/v3/webhooks/endpoints

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/webhooks/endpoints
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

urlstring required

Publicly accessible HTTPS URL that will receive webhook POST requests.

eventsWebhookEventType[] nullable

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

entity_idstring nullable

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

Response

Successful response

Example response

{
  "data": {
    "endpoint_id": "ep_abc123def456",
    "url": "https://example.com/webhook",
    "events": [
      "avatar_video.success",
      "avatar_video.fail"
    ],
    "status": "enabled",
    "created_at": "2024-04-01T12:00:00Z",
    "secret": "whsec_abc123def456"
  }
}

Changes

  • 7dfa5e59b4f5Revision changes
    • info

      added the new filler_word_removal.fail enum value to the request property //

    • info

      added the new filler_word_removal.success enum value to the request property //

    • info

      added the new podcast.fail enum value to the request property //

    • info

      added the new podcast.success enum value to the request property //

    • info

      added the new video_generation.fail enum value to the request property //

    • info

      added the new video_generation.success enum value to the request property //

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status