> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Webhook events

> VideoGen sends webhook events when tool executions, workflow runs, project exports, files, and assistant messages finish processing. Events follow the Standard Webhooks spec and include signed headers for verification.

VideoGen sends events to your registered webhook endpoints when asynchronous work completes. There are five categories of events:

| Category              | Events                                                                                                                                         | When they fire                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Tool execution**    | `tool_execution.succeeded`, `tool_execution.failed`, `tool_execution.cancelled`                                                                | A tool run reaches a terminal state.                                                                        |
| **Workflow run**      | `workflow_run.succeeded`, `workflow_run.failed`, `workflow_run.cancelled`                                                                      | A workflow started via `POST /v1/workflows/*` reaches a terminal state.                                     |
| **Project export**    | `project_export.succeeded`, `project_export.failed`, `project_export.cancelled`                                                                | An export started via `POST /v1/projects/{projectId}/export` reaches a terminal state.                      |
| **File upload**       | `file.upload.completed`, `file.upload.failed`, `file.playback_ready`, `file.download_ready`, `file.analysis_completed`, `file.analysis_failed` | A file uploaded via the API progresses through processing stages.                                           |
| **Assistant message** | `assistant_message.succeeded`, `assistant_message.failed`, `assistant_message.cancelled`                                                       | An assistant message from `POST /v1/assistants` or follow-up message/action calls reaches a terminal state. |

## Delivery format

All events are delivered as `POST` requests with a JSON body. Every payload includes:

| Field        | Type     | Description                                       |
| ------------ | -------- | ------------------------------------------------- |
| `event`      | `string` | The event name (e.g. `tool_execution.succeeded`). |
| `occurredAt` | `number` | Unix timestamp (seconds) when the event occurred. |

## Signature verification

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) spec. Each request includes three headers:

| Header              | Purpose                                 |
| ------------------- | --------------------------------------- |
| `webhook-id`        | Unique message id for deduplication.    |
| `webhook-timestamp` | Unix timestamp of the attempt.          |
| `webhook-signature` | HMAC-SHA256 signature for verification. |

Both SDKs ship a `verifyWebhookSignature` helper:

**TypeScript:**

```typescript
import { verifyWebhookSignature } from "@videogen/sdk";

const payload = verifyWebhookSignature(
  rawBody,
  request.headers,
  signingSecret,
);
```

**Python:**

```python
from videogen import verify_webhook_signature

payload = verify_webhook_signature(
    raw_body=request.data.decode(),
    headers=dict(request.headers),
    signing_secret=signing_secret,
)
```

The helpers throw if the signature is invalid or the timestamp is too old.

## Registering for events

Use the [Create webhook endpoint](/rest-api-reference/webhooks/create-webhook-endpoint) to register a URL and select which events to receive. The signing secret is only returned once on creation. Store it securely.

```bash
curl -X POST https://api.videogen.io/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_videogen_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/videogen",
    "events": ["tool_execution.succeeded", "tool_execution.failed", "workflow_run.succeeded", "project_export.succeeded"]
  }'
```

## Retry behavior

If your endpoint returns a non-2xx status code or doesn't respond within 15 seconds, VideoGen will retry with exponential backoff. Use the `webhook-id` header to deduplicate retries.

## Learn more

* [Webhooks guide](/handling-async-tasks/webhooks) — step-by-step setup, signature verification examples, and file upload webhook details
* [Webhook management API](/rest-api-reference/webhooks/list-webhook-endpoints) — create, list, and delete webhook endpoints programmatically