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": ["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 incoming events

When an execution reaches a terminal status, VideoGen sends a POST request to your URL:

1
{
2
  "event": "tool_execution.succeeded",
3
  "toolExecutionId": "vg_exec_...",
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.

3. 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_exec_..."

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