Get Video Results with Webhooks

Use this guide when you need to add webhook-based video completion handling instead of polling from a client or worker.

By the end, your implementation should submit a video job with callback_url and verify the webhook signature.

Before you start

You need:

• An OpenRouter API key available as OPENROUTER_API_KEY
• Node.js 20 or newer
• A public HTTPS endpoint for your webhook receiver
• A webhook signing secret configured in your OpenRouter workspace settings
• A video model slug for the job you submit with callback_url

Use the API reference pages as the source of truth for exact fields:

• Create video generation request
• List video generation models
• TypeScript SDK video generation reference

If you adapt the Express examples below in a local test project, use these dependencies:

$
npm install express
$
npm install --save-dev @types/express tsx

Step 1: Implement a webhook receiver

Add a webhook receiver that preserves the raw request body before parsing JSON. Signature verification must use the exact bytes OpenRouter sent, not a re-serialized payload.

Example Express receiver:

1
import crypto from "node:crypto";
2
import express from "express";
3
4
const app = express();
5
const signingSecret = process.env.OPENROUTER_WEBHOOK_SECRET;
6
7
type VideoWebhookEvent = {
8
  type:
9
    | "video.generation.completed"
10
    | "video.generation.failed"
11
    | "video.generation.cancelled"
12
    | "video.generation.expired";
13
  created_at: string;
14
  data: {
15
    id: string;
16
    status: "completed" | "failed" | "cancelled" | "expired";
17
    generation_id?: string | null;
18
    model?: string | null;
19
    unsigned_urls?: string[];
20
    usage?: {
21
      cost?: number;
22
      is_byok?: boolean;
23
    };
24
    error?: string;
25
  };
26
};
27
28
function verifyOpenRouterSignature(rawBody: Buffer, header: string): boolean {
29
  if (!signingSecret) return false;
30
31
  const parts = header.split(",").map((part) => part.trim());
32
  const timestamp = parts.find((part) => part.startsWith("t="))?.slice(2);
33
  const signature = parts.find((part) => part.startsWith("v1="))?.slice(3);
34
35
  if (!timestamp || !signature) return false;
36
37
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
38
  if (Number.isNaN(age) || Math.abs(age) > 300) return false;
39
40
  const signedPayload = Buffer.concat([
41
    Buffer.from(`${timestamp},`, "utf8"),
42
    rawBody,
43
  ]);
44
  const expected = crypto
45
    .createHmac("sha256", signingSecret)
46
    .update(signedPayload)
47
    .digest("hex");
48
49
  if (expected.length !== signature.length) return false;
50
51
  return crypto.timingSafeEqual(
52
    Buffer.from(expected),
53
    Buffer.from(signature),
54
  );
55
}
56
57
app.post(
58
  "/openrouter/video-webhook",
59
  express.raw({ type: "application/json" }),
60
  (req, res) => {
61
    const signature = req.header("X-OpenRouter-Signature");
62
63
    if (!signature || !verifyOpenRouterSignature(req.body, signature)) {
64
      return res.sendStatus(401);
65
    }
66
67
    const idempotencyKey = req.header("X-OpenRouter-Idempotency-Key");
68
    const event = JSON.parse(req.body.toString("utf8")) as VideoWebhookEvent;
69
    const job = event.data;
70
71
    if (job.status === "completed") {
72
      console.log("Video ready:", {
73
        id: job.id,
74
        idempotencyKey,
75
        url: job.unsigned_urls?.[0],
76
      });
77
    }
78
79
    if (["failed", "cancelled", "expired"].includes(job.status)) {
80
      console.error("Video did not complete:", {
81
        id: job.id,
82
        status: job.status,
83
        error: job.error,
84
        idempotencyKey,
85
      });
86
    }
87
88
    res.sendStatus(204);
89
  },
90
);
91
92
app.listen(3000, () => {
93
  console.log("Listening on http://localhost:3000");
94
});

Step 2: Validate signature handling before using real jobs

Before connecting a real callback_url, exercise the receiver with the same signing secret your test sender uses:

$
OPENROUTER_WEBHOOK_SECRET=dev_secret npx tsx server.ts

Actual local receiver startup output:

Listening on http://localhost:3000

Expose the receiver with a public HTTPS URL before using it as a real callback_url. A local tunnel or deployed preview URL works as long as OpenRouter can reach it over HTTPS.

Step 3: Send a signed test event

Before spending credits on a real video job, test the receiver with a locally signed event. This verifies that raw-body handling, timestamp parsing, HMAC comparison, and idempotency headers are wired correctly.

Example local sender:

1
import crypto from "node:crypto";
2
3
const secret = process.env.OPENROUTER_WEBHOOK_SECRET;
4
5
if (!secret) {
6
  throw new Error("Set OPENROUTER_WEBHOOK_SECRET first.");
7
}
8
9
const body = JSON.stringify({
10
  type: "video.generation.completed",
11
  created_at: new Date().toISOString(),
12
  data: {
13
    id: "job_test",
14
    status: "completed",
15
    unsigned_urls: ["https://example.com/video.mp4"],
16
  },
17
});
18
const timestamp = Math.floor(Date.now() / 1000).toString();
19
const signature = crypto
20
  .createHmac("sha256", secret)
21
  .update(`${timestamp},${body}`)
22
  .digest("hex");
23
24
const response = await fetch("http://localhost:3000/openrouter/video-webhook", {
25
  method: "POST",
26
  headers: {
27
    "Content-Type": "application/json",
28
    "X-OpenRouter-Signature": `t=${timestamp},v1=${signature}`,
29
    "X-OpenRouter-Idempotency-Key": "job_test-completed",
30
  },
31
  body,
32
});
33
34
console.log(response.status);

Exercise the local sender while the receiver is listening:

$
OPENROUTER_WEBHOOK_SECRET=dev_secret node send-test-webhook.mjs

A valid signed event should return 204. Change the secret or signature to confirm the receiver returns 401 for invalid requests.

Actual local signature-test output:

204

You can also use a temporary Webhook.site URL as CALLBACK_URL to confirm OpenRouter delivers the webhook and includes the expected headers and envelope. Webhook.site does not run your signature verifier; use your own public receiver with the workspace signing secret for end-to-end signature verification.

Example Webhook.site delivery:

1
{
2
  "request": {
3
    "method": "POST",
4
    "content_type": "application/json",
5
    "has_signature_header": true,
6
    "signature": {
7
      "has_timestamp": true,
8
      "has_v1": true,
9
      "redacted_format": "t=<timestamp>,v1=<hex>"
10
    },
11
    "has_idempotency_key_header": true,
12
    "idempotency_key_shape": {
13
      "includes_job_id": true,
14
      "length": 30
15
    },
16
    "body_shape": {
17
      "top_level_keys": ["created_at", "data", "type"],
18
      "type": "video.generation.completed",
19
      "data_keys": [
20
        "generation_id",
21
        "id",
22
        "model",
23
        "status",
24
        "unsigned_urls",
25
        "usage"
26
      ],
27
      "data_id_matches_job": true,
28
      "data_status": "completed",
29
      "unsigned_url_count": 1,
30
      "usage_keys": ["cost", "is_byok"]
31
    }
32
  },
33
  "job": {
34
    "id": "Nxff2D1Z6w4Zk9iNuZam",
35
    "poll_statuses": [
36
      { "status": "pending", "elapsed_seconds": 1 },
37
      { "status": "pending", "elapsed_seconds": 11 },
38
      { "status": "pending", "elapsed_seconds": 21 },
39
      { "status": "pending", "elapsed_seconds": 31 },
40
      { "status": "completed", "elapsed_seconds": 41 }
41
    ],
42
    "downloaded_bytes": 442723
43
  }
44
}

Step 4: Submit a video job with callback_url

Once the receiver is reachable over public HTTPS, submit the video job with callback_url. The callback URL can be set per request, which is useful for preview environments or tenant-specific receivers.

Example submit logic:

1
const apiKey = process.env.OPENROUTER_API_KEY;
2
const callbackUrl = process.env.CALLBACK_URL;
3
4
if (!apiKey) {
5
  throw new Error("Set OPENROUTER_API_KEY first.");
6
}
7
8
if (!callbackUrl) {
9
  throw new Error("Set CALLBACK_URL to your public HTTPS receiver URL.");
10
}
11
12
const response = await fetch("https://openrouter.ai/api/v1/videos", {
13
  method: "POST",
14
  headers: {
15
    Authorization: `Bearer ${apiKey}`,
16
    "Content-Type": "application/json",
17
  },
18
  body: JSON.stringify({
19
    model: "google/veo-3.1-lite",
20
    prompt: "A clean product reveal of a matte black desk lamp, slow camera slide, studio lighting",
21
    duration: 4,
22
    resolution: "720p",
23
    aspect_ratio: "16:9",
24
    generate_audio: false,
25
    callback_url: callbackUrl,
26
  }),
27
});
28
29
if (!response.ok) {
30
  throw new Error(await response.text());
31
}
32
33
console.log(await response.json());

The submit call returns the initial job fields. In a completed run, that job later completed and delivered a webhook with this final summary:

1
{
2
  "id": "Nxff2D1Z6w4Zk9iNuZam",
3
  "initial_status": "pending",
4
  "terminal_status": "completed",
5
  "response_keys": ["id", "polling_url", "status"]
6
}

After the receiver is deployed or exposed through a tunnel, run the submit logic with CALLBACK_URL set to that public endpoint:

$
CALLBACK_URL=https://your-app.example.com/openrouter/video-webhook npx tsx submit-video-job.mts

The per-request callback_url takes priority over a workspace-level default callback URL.

Step 5: Handle the completed job

Handle webhook delivery as a terminal job update. The payload is an event envelope with the job fields inside data; the data object includes fields such as id, status, generation_id, model, unsigned_urls, usage, and error, depending on the terminal state. Store the job state in your database, deduplicate retries with X-OpenRouter-Idempotency-Key, then download the video from the first unsigned_urls entry or from the content endpoint. If the URL points to the OpenRouter API, include the bearer token when downloading it.

For a complete polling and download helper, see Generate and Download a Video from Text.

Actual local receiver log shape from the signature test:

Video ready: {
  id: "job_test",
  idempotencyKey: "job_test-completed",
  url: "https://example.com/video.mp4"
}

Check your work

Your receiver should return 204 for a valid OpenRouter webhook and 401 for a request with a missing or invalid signature. A real callback delivery should produce a terminal job update that your app can store and use to download the generated video.