> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.videogen.io/webhook-events/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server. # Webhook events > HTTP API with TypeScript and Python SDKs for generating image, video, and audio assets with VideoGen. ## API Docs - Webhook events > Webhook Events [tool_execution.succeeded](https://docs.videogen.io/webhook-events/webhook-events/tool-execution-succeeded.md) - Webhook events > Webhook Events [tool_execution.failed](https://docs.videogen.io/webhook-events/webhook-events/tool-execution-failed.md) - Webhook events > Webhook Events [tool_execution.cancelled](https://docs.videogen.io/webhook-events/webhook-events/tool-execution-cancelled.md) - Webhook events > Webhook Events [workflow_run.succeeded](https://docs.videogen.io/webhook-events/webhook-events/workflow-run-succeeded.md) - Webhook events > Webhook Events [workflow_run.failed](https://docs.videogen.io/webhook-events/webhook-events/workflow-run-failed.md) - Webhook events > Webhook Events [workflow_run.cancelled](https://docs.videogen.io/webhook-events/webhook-events/workflow-run-cancelled.md) - Webhook events > Webhook Events [project_export.succeeded](https://docs.videogen.io/webhook-events/webhook-events/project-export-succeeded.md) - Webhook events > Webhook Events [project_export.failed](https://docs.videogen.io/webhook-events/webhook-events/project-export-failed.md) - Webhook events > Webhook Events [project_export.cancelled](https://docs.videogen.io/webhook-events/webhook-events/project-export-cancelled.md) - Webhook events > Webhook Events [file.upload.completed](https://docs.videogen.io/webhook-events/webhook-events/file-upload-completed.md) - Webhook events > Webhook Events [file.upload.failed](https://docs.videogen.io/webhook-events/webhook-events/file-upload-failed.md) - Webhook events > Webhook Events [file.playback_ready](https://docs.videogen.io/webhook-events/webhook-events/file-playback-ready.md) - Webhook events > Webhook Events [file.download_ready](https://docs.videogen.io/webhook-events/webhook-events/file-download-ready.md) - Webhook events > Webhook Events [file.analysis_completed](https://docs.videogen.io/webhook-events/webhook-events/file-analysis-completed.md) - Webhook events > Webhook Events [file.analysis_failed](https://docs.videogen.io/webhook-events/webhook-events/file-analysis-failed.md) - Webhook events > Webhook Events [assistant_message.succeeded](https://docs.videogen.io/webhook-events/webhook-events/assistant-message-succeeded.md) - Webhook events > Webhook Events [assistant_message.failed](https://docs.videogen.io/webhook-events/webhook-events/assistant-message-failed.md) - Webhook events > Webhook Events [assistant_message.cancelled](https://docs.videogen.io/webhook-events/webhook-events/assistant-message-cancelled.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.videogen.io/webhook-events/openapi.json) - [OpenAPI YAML](https://docs.videogen.io/webhook-events/openapi.yaml) > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.videogen.io/webhook-events/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