Webhook events

Event payloads delivered to your registered webhook endpoints.

VideoGen sends events to your registered webhook endpoints when asynchronous work completes. There are two 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.
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.

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 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

Python

1 import { verifyWebhookSignature } from "@videogen/sdk";
2 
3 const payload = verifyWebhookSignature(
4   rawBody,
5   request.headers,
6   signingSecret,
7 );

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

Registering for events

Use the 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.

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

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 — step-by-step setup, signature verification examples, and file upload webhook details
Webhook management API — create, list, and delete webhook endpoints programmatically

1	import { verifyWebhookSignature } from "@videogen/sdk";
2
3	const payload = verifyWebhookSignature(
4	rawBody,
5	request.headers,
6	signingSecret,
7	);

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