Webhooks

For production systems, webhooks are the better choice. Instead of polling, you register a URL and VideoGen sends you an event when work completes. For the full list of event types and payload schemas, see the Webhook events reference.

1. Register a webhook endpoint

$
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": ["workflow_run.succeeded", "workflow_run.failed", "workflow_run.cancelled", "tool_execution.succeeded", "tool_execution.failed", "tool_execution.cancelled", "assistant_message.succeeded", "assistant_message.failed", "assistant_message.cancelled"]
>
  }'

The response includes a signingSecret. Save it; you’ll need it to verify incoming requests.

2. Handle workflow run events

Subscribe to workflow_run.succeeded, workflow_run.failed, and workflow_run.cancelled to track end-to-end video workflows started via POST /v1/workflows/*. When a run reaches a terminal status, VideoGen sends a POST request to your URL:

1
{
2
  "event": "workflow_run.succeeded",
3
  "workflowRunId": "vg_work_...",
4
  "occurredAt": 1745409600,
5
  "workflowType": "SCRIPT_TO_VIDEO",
6
  "projectId": "vg_proj_...",
7
  "projectUrl": "https://app.videogen.io/project/..."
8
}

Payloads include workflowRunId, workflowType, projectId, and projectUrl. Failed events also include an error.message field. Use projectId with the Projects API to export or remix. projectUrl is an optional deep link for opening the project in the VideoGen editor (team members and project collaborators only); you can ignore it in a fully automated integration.

3. Handle tool execution events

Standalone media tools emit tool_execution.succeeded, tool_execution.failed, and tool_execution.cancelled. The success payload carries the generated files inline:

1
{
2
  "event": "tool_execution.succeeded",
3
  "toolExecutionId": "vg_tool_...",
4
  "toolType": "GENERATE_IMAGE",
5
  "occurredAt": 1745409600,
6
  "results": [
7
    {
8
      "fileId": "vg_file_...",
9
      "type": "IMAGE",
10
      "file": {
11
        "fileId": "vg_file_...",
12
        "type": "IMAGE",
13
        "scope": "GLOBAL",
14
        "displayName": "A mountain at sunrise",
15
        "thumbnailSource": { "status": "ready", "url": "https://...", "expiresAt": 1745413200 },
16
        "previewSource": { "status": "ready", "url": "https://...", "expiresAt": 1745413200 },
17
        "downloadSource": { "status": "ready", "url": "https://...", "expiresAt": 1745413200 }
18
      }
19
    }
20
  ]
21
}

Each entry in results contains the file id, type, and a hydrated file object with signed download URLs, so no extra API call is needed. For tool_execution.failed and tool_execution.cancelled events, results is absent.

4. Handle assistant message events

Assistant chat POSTs (POST /v1/assistants, POST /v1/assistants/{assistantId}/messages, POST /v1/assistants/{assistantId}/actions/{actionId}) emit assistant_message.succeeded, assistant_message.failed, and assistant_message.cancelled. The payload mirrors GET /v1/assistant-messages/{messageId}: poll that endpoint if you need the full message after receiving the event.

5. Verify signatures

Webhook deliveries follow the Standard Webhooks spec. Both SDKs ship a verifyWebhookSignature helper so you can confirm a request is authentic without pulling in the standardwebhooks library yourself:

1
import { verifyWebhookSignature } from "@videogen/sdk";
2
3
// In your webhook handler (e.g. Express, Next.js API route):
4
const payload = verifyWebhookSignature(
5
  rawBody, // the raw request body string (not parsed JSON)
6
  request.headers, // must include webhook-id, webhook-timestamp, webhook-signature
7
  signingSecret, // the secret returned when you created the endpoint
8
);
9
10
console.log(payload.event); // "tool_execution.succeeded"
11
console.log(payload.toolExecutionId); // "vg_tool_..."

The helpers throw if the signature is invalid or the timestamp is too old, so catch the error to reject the request.

File upload webhooks

In addition to tool execution events, you can subscribe to file upload lifecycle events. These are only fired for files uploaded via the API (not the VideoGen UI).

Register for file events the same way as tool events:

$
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": ["file.upload.completed", "file.playback_ready", "file.download_ready", "file.analysis_completed"]
>
  }'

Next steps

• Webhook events reference — full list of event types and payload schemas
• Webhook management API — create, list, and delete webhook endpoints programmatically