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 $VIDEOGEN_API_KEY" \
>
  -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"]
>
  }'

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": "2026-05-23T12:00:00.000Z",
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. Open projectUrl in the app or export the project via the Projects API.

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. 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 $VIDEOGEN_API_KEY" \
>
  -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