Skip to navigation
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 five categories of events:

CategoryEventsWhen they fire
Tool executiontool_execution.succeeded, tool_execution.failed, tool_execution.cancelledA tool run reaches a terminal state.
Workflow runworkflow_run.succeeded, workflow_run.failed, workflow_run.cancelledA workflow started via POST /v1/workflows/* reaches a terminal state.
Project exportproject_export.succeeded, project_export.failed, project_export.cancelledAn export started via POST /v1/projects/{projectId}/export 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.
Assistant messageassistant_message.succeeded, assistant_message.failed, assistant_message.cancelledAn 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:

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:

import { verifyWebhookSignature } from "@videogen/sdk";
const payload = verifyWebhookSignature(
  rawBody,
  request.headers,
  signingSecret,
);

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