> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive HeyGen API webhook events when videos finish rendering, translations complete, or errors occur. Includes endpoint setup, signature verification, and.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-1.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=75889d32f3d54871cdb75d24c86b82da)

Instead of polling [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) for status, you can register a webhook endpoint to receive a POST notification when a video completes, fails, or other events occur. See [Webhook Events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md) for the full event catalog and payload shapes.

Authentication is the same `X-Api-Key` header as the rest of the v3 API; see the [API Key guide](https://heygen-1fa696a7.mintlify.site/docs/api-key.md).

## Create an Endpoint

Register a URL to receive webhook events with [`POST /v3/webhooks/endpoints`](https://heygen-1fa696a7.mintlify.site/reference/create-webhook-endpoint). The response includes an `endpoint_id` and a `secret` for verifying payloads: store it securely, as it will not be shown again.

```bash theme={null}
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"]
  }'
```

`url` must be a publicly accessible HTTPS URL. Omit `events` or set it to `null` to receive all events; see [Webhook Events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md) and [`GET /v3/webhooks/event-types`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-event-types) for the full list. `entity_id` scopes the endpoint to a specific resource (e.g. a personalized video project).

## Manage Endpoints

* **List:** [`GET /v3/webhooks/endpoints`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-endpoints), paged with `limit` (1–100, default `10`) and `token`. The `secret` field is only returned when creating an endpoint or rotating the secret; it is `null` in list responses.
* **Update:** [`PATCH /v3/webhooks/endpoints/{endpoint_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-webhook-endpoint) changes `url` and/or `events`; include only what you want to change. The `events` array is fully replaced, so include all event types you want to keep.
* **Delete:** [`DELETE /v3/webhooks/endpoints/{endpoint_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-webhook-endpoint) permanently removes an endpoint. Events will no longer be delivered to this URL.

## Rotate Signing Secret

[`POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`](https://heygen-1fa696a7.mintlify.site/reference/rotate-webhook-signing-secret) returns a new `secret`. The old secret is invalidated immediately on rotation; deploy the new secret to your verifier promptly. Expect a brief window of failed verifications during rollover, and handle this gracefully on the receiver.

## Verifying Payloads

Every webhook delivery includes a signature header derived from your endpoint `secret`. **Always verify before trusting the payload** — without verification, anyone who learns your URL can forge events.

HeyGen signs the **raw request body** with HMAC-SHA256 using the endpoint `secret` returned by [Create Endpoint](https://heygen-1fa696a7.mintlify.site/reference/create-webhook-endpoint.md) or [Rotate Secret](https://heygen-1fa696a7.mintlify.site/reference/rotate-webhook-signing-secret.md). Compute the same digest on your side and compare in constant time.

| Header | Description |
| - | - |
| `signature` | Hex-encoded HMAC-SHA256 of the raw request body, computed with your endpoint `secret`. HTTP header names are case-insensitive, so `signature` and `Signature` refer to the same header. |

```javascript Node.js theme={null}
import crypto from "node:crypto";
import express from "express";

const app = express();
// IMPORTANT: keep the raw body intact for signature verification.
app.use("/webhooks/heygen", express.raw({ type: "application/json" }));

const SECRET = process.env.HEYGEN_WEBHOOK_SECRET;

app.post("/webhooks/heygen", (req, res) => {
  const signature = req.header("signature");

  if (!signature) return res.status(400).send("missing signature");

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(req.body) // raw Buffer, not parsed JSON
    .digest("hex");

  const sigBuf = Buffer.from(signature, "hex");
  const expBuf = Buffer.from(expected, "hex");
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).send("bad signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // Handle event.event_type — see /docs/webhook-events for the catalog.
  res.status(200).send("ok");
});
```

```python Python (Flask) theme={null}
import hashlib
import hmac
import os
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["HEYGEN_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/heygen")
def heygen_webhook():
    signature = request.headers.get("signature", "")
    if not signature:
        abort(400, "missing signature")

    raw = request.get_data()  # bytes, before any JSON parsing
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401, "bad signature")

    event = request.get_json()
    # Handle event["event_type"] — see /docs/webhook-events for the catalog.
    return "", 200
```

> [!WARNING]
>
> Verify against the **raw body bytes**, not a re-serialized JSON object. Any whitespace or key-order change will break the HMAC. In Express, use `express.raw()`; in Flask, use `request.get_data()` before `request.get_json()`.

### Delivery, retries, and idempotency

* **Success criteria:** respond with `2xx` within 10 seconds. Slow handlers will be timed out and retried.
* **Retries:** failed deliveries are retried with exponential backoff for up to 24 hours.
* **Idempotency:** a single event can be delivered more than once (a retry after a transient failure). A retry resends the **same payload**, so de-duplicate on a stable field in the body. For avatar video events, use `event_data.video_id` together with `event_type`, or the `callback_id` you set when creating the video.

For the full list of event types and payload shapes, see [Webhook Events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md).

## Using Callbacks Instead

If you don't need a persistent webhook endpoint, pass a `callback_url` directly when creating a video, for example via [Create Video Agent Session](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session.md) or [Create Video Translation](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation.md). This sends a one-off notification for that specific request without registering an endpoint:

```json "Video Agent with callback" theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.