Webhook events

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:

CategoryEventsWhen they fire
Tool executiontool_execution.succeeded, tool_execution.failed, tool_execution.cancelledA tool run reaches a terminal state.
File uploadfile.upload.completed, file.upload.failed, file.playback_ready, file.download_ready, file.analysis_completed, file.analysis_failedA 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:

FieldTypeDescription
eventstringThe event name (e.g. tool_execution.succeeded).
occurredAtnumberUnix timestamp (seconds) when the event occurred.

Signature verification

Deliveries follow the Standard Webhooks spec. Each request includes three headers:

HeaderPurpose
webhook-idUnique message id for deduplication.
webhook-timestampUnix timestamp of the attempt.
webhook-signatureHMAC-SHA256 signature for verification.

Both SDKs ship a verifyWebhookSignature helper:

1import { verifyWebhookSignature } from "@videogen/sdk";
2
3const 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