Webhooks

Overview

Every create endpoint, and POST /v1/render, takes an optional webhook URL. When the video finishes, or the project fails, Hooked sends a signed POST with JSON to that URL (Content-Type: application/json). The URL you pass on create belongs to that project and is called for its automatic render. A render started later with POST /v1/render calls only the webhook passed in that request, and a render started from the dashboard editor calls none. You can also register team endpoints in the dashboard under Settings → Webhooks. Each one picks the events it wants and receives them for every project and render in the team, whether it was started from the API or the dashboard. If you pass no webhook and register no endpoint, nothing is sent and you can poll GET /v1/project/{projectId} instead.

How it works

Pass a webhook URL

{
  "avatarId": "1",
  "script": "Your script...",
  "webhook": "https://yoursite.com/hooks/hooked",
  "metadata": { "userId": "u_42" }
}

Hooked generates the video

The create call answers right away with a projectId. Generation takes a few minutes depending on the format.

Hooked calls your URL

Once the video is rendered, or when the project fails, your URL gets a POST with the result.

Verify the signature, then answer 2xx quickly

Respond with any 2xx status within 10 seconds. Do the slow work (downloading, emailing) after you answer.

URL requirements

https:// only. Anything else is rejected at create time with 400 webhook: Must be a valid HTTPS URL.
A public host. A URL that names localhost, a private IP, a *.local/*.internal host or a cloud metadata address is refused at create time with the same 400. A hostname that only resolves to a private address is accepted on create, but the call is never sent.
Up to 500 characters.
Redirects are not followed. A 3xx counts as a failed attempt, so give the final URL.

Payloads

The body has no event field (it is the same body Hooked has always sent). Read the top-level status, COMPLETED or FAILED, or the Hooked-Event header.

Headers and events

Every call carries these headers:

Header	Value
`Hooked-Signature`	`t=<unix seconds>,v1=<hex signature>`. See Verify the signature.
`Hooked-Event`	The event name, below.
`Hooked-Delivery`	A unique id for this delivery, such as `dlv_3f9a…`. Retries of the same delivery keep it, so you can use it to drop duplicates.

Event	Sent when	Body `status`
`video.completed`	A video finished rendering.	`COMPLETED`
`video.failed`	A render failed or timed out.	`FAILED`
`project.failed`	A project failed before it had a video.	`FAILED`
`media.completed`	A library image or video is ready: a Media Generator run, an import or an upload.	`COMPLETED`
`media.failed`	A library image or video failed or timed out.	`FAILED`

The per-request webhook URL of a project gets the first three; the one of a media call gets the media.* pair (see Media webhooks). A team endpoint gets only the events it subscribed to.

Video completed

{
  "status": "COMPLETED",
  "message": "Video completed",
  "data": {
    "videoId": "cm9x2m1cd0002qz8fa8b7c6d5",
    "projectId": "cm9x2k7ab0001qz8f3h1d2e4f",
    "status": "COMPLETED",
    "url": "https://...mp4",
    "shareUrl": "https://hooked.so/shared/...",
    "metadata": { "userId": "u_42" }
  }
}

Render failed or timed out

{
  "status": "FAILED",
  "message": "Video rendering failed",
  "data": {
    "videoId": "cm9x2m1cd0002qz8fa8b7c6d5",
    "projectId": "cm9x2k7ab0001qz8f3h1d2e4f",
    "status": "FAILED",
    "url": ""
  }
}

message is Video rendering failed, Video rendering timed out or Video failed.

Project failed before it had a video

If the project fails while it is still generating (a provider error, running out of credits mid-way), there is no video yet, so videoId is null:

{
  "status": "FAILED",
  "message": "Failed to create UGC video",
  "data": {
    "videoId": null,
    "projectId": "cm9x2k7ab0001qz8f3h1d2e4f",
    "status": "FAILED",
    "url": "",
    "metadata": { "userId": "u_42" }
  }
}

message is the project’s own failure message. Credits charged for a failed project are refunded automatically.

Some failures while generating do not send this call yet (for example, a narrated video whose AI images or clips failed). Always poll GET /v1/project/{projectId} as a backup when no webhook arrives.

Fields

string

COMPLETED or FAILED.

string

A human-readable summary. On failures, the reason.

object

Show data

string | null

The rendered video. null when the project failed before rendering.

string

The projectId the create call returned.

string

Same as the top-level status.

string

The video file on success, "" on failure. The link can be signed and expire: download the file and keep your own copy. GET /v1/project/{projectId} gives a fresh link.

Only when the project has public sharing turned on.

object

The metadata object you sent on create (up to 5 KB), returned as is; {} when you sent none. Not included on render failures.

Media webhooks

POST /v1/media/generate/image, POST /v1/media/generate/video and POST /v1/media/import also take an optional webhook (same URL requirements) and metadata (any JSON object, up to 5 KB). The URL is told once, when the media becomes COMPLETED or FAILED, with the event media.completed or media.failed, signed with the same request signing secret as project webhooks. Team endpoints subscribed to media.completed / media.failed get the same body for every library generation, import and upload of the team, from the API or the dashboard.

{
  "status": "COMPLETED",
  "message": "Media completed",
  "data": {
    "mediaId": "cm4x9s8u60009ab12kl56mn90",
    "status": "COMPLETED",
    "url": "https://...png",
    "type": "image",
    "error": null,
    "metadata": { "sku": "serum-30ml" }
  }
}

{
  "status": "FAILED",
  "message": "The URL answered 404",
  "data": {
    "mediaId": "cm4x9s8u60009ab12kl56mn90",
    "status": "FAILED",
    "url": "",
    "type": "image",
    "error": "The URL answered 404",
    "metadata": { "sku": "serum-30ml" }
  }
}

url is the file, signed and expiring like every Hooked link; "" when FAILED. Get Media gives a fresh one.
type is image or video.
error is why it failed (null when COMPLETED); Get Media shows the same text. A failed generation’s credits are refunded automatically.
metadata is the object you sent, or null.

A media still running after 60 minutes is given up on: it becomes FAILED and media.failed is sent then. Poll Get Media as a backup when no webhook arrives.

Retries

Hooked tries each delivery up to 3 times in a row, with no delay between attempts. An attempt fails when your endpoint answers anything other than 2xx, does not answer within 10 seconds, or the connection fails. After the third failed attempt the notification is dropped. Because of that:

Answer fast and do the work afterwards.
Do not rely on the webhook alone. If your endpoint was down, poll GET /v1/project/{projectId} to catch up.
Handle duplicates. If your endpoint processed a call but answered too late, the same payload arrives again with the same Hooked-Delivery id. Use that id, or videoId (projectId when videoId is null), to ignore repeats.

Verify the signature

Every call is signed with HMAC-SHA256, so you can tell that it came from Hooked and was not changed on the way.

Where to find the secret

In the dashboard, open Settings → Webhooks:

Signing secret signs the calls to the webhook URL you pass in API requests. There is one per team, created the first time it is needed.
Each team endpoint has its own secret, shown on its row.

Both start with whsec_. Click the eye icon to reveal one. Rotate creates a new secret at once and the old one stops working, so update your server right after.

How the signature is built

Hooked-Signature: t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is the hex HMAC-SHA256 of "<t>.<raw body>" using the secret as the key. To check it:

Read t and v1 from the header.
Reject the call if t is more than 5 minutes away from your clock (stops replays).
Compute the HMAC over t, a ., and the raw request body exactly as received. Do not parse and re-serialize the JSON first: any change breaks the signature.
Compare it with v1 in constant time.

Node.js

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verifyHookedSignature(rawBody, header, secret) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = parts.v1 ?? "";
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_hooked_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
    if not header:
        return False
    parts = dict(item.split("=", 1) for item in header.split(","))
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False

    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Extra checks

A token in the URL (?token=...) is no longer needed, but you can still add one as a second check.
Do not trust the payload blindly for sensitive actions: confirm it with GET /v1/project/{projectId} using your API key. This also gives you a fresh download link.
Use your own correlation ids in metadata so you know which of your records a call belongs to.

Implementing an endpoint

Node.js (Express)

import express from "express";
import { verifyHookedSignature } from "./verify-hooked-signature.js"; // the function above

const app = express();
const SECRET = process.env.HOOKED_WEBHOOK_SECRET; // whsec_...
const seen = new Set(); // use your database in production

// Raw body: the signature covers the exact bytes Hooked sent
app.post("/hooks/hooked", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  if (!verifyHookedSignature(rawBody, req.get("Hooked-Signature"), SECRET)) {
    return res.sendStatus(401);
  }

  const { status, message, data } = JSON.parse(rawBody);
  const deliveryId = req.get("Hooked-Delivery");

  // Answer first, work after
  res.sendStatus(200);

  if (seen.has(deliveryId)) return;
  seen.add(deliveryId);

  if (status === "COMPLETED") {
    console.log(`Video ${data.videoId} ready for project ${data.projectId}: ${data.url}`);
    // download data.url, update your records using data.metadata
  } else {
    console.error(`Project ${data.projectId} failed: ${message}`);
  }
});

app.listen(3000);

Python (FastAPI)

import json
import os
from fastapi import BackgroundTasks, FastAPI, HTTPException, Request

from verify import verify_hooked_signature  # the function above

app = FastAPI()
SECRET = os.environ["HOOKED_WEBHOOK_SECRET"]  # whsec_...


def handle(payload: dict) -> None:
    data = payload["data"]
    if payload["status"] == "COMPLETED":
        print(f"Video {data['videoId']} ready: {data['url']}")
    else:
        print(f"Project {data['projectId']} failed: {payload['message']}")


@app.post("/hooks/hooked")
async def hooked_webhook(request: Request, background_tasks: BackgroundTasks):
    raw_body = await request.body()
    if not verify_hooked_signature(raw_body, request.headers.get("Hooked-Signature"), SECRET):
        raise HTTPException(status_code=401)
    background_tasks.add_task(handle, json.loads(raw_body))
    return {"received": True}

Next.js route handler

// app/api/hooks/hooked/route.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyHookedSignature } from "@/lib/verify-hooked-signature"; // the function above

export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("Hooked-Signature");
  if (!verifyHookedSignature(rawBody, signature, process.env.HOOKED_WEBHOOK_SECRET!)) {
    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
  }

  const { status, message, data } = JSON.parse(rawBody);

  if (status === "COMPLETED") {
    // Save data.videoId / data.url against data.metadata
  } else {
    console.error(`Project ${data.projectId} failed: ${message}`);
  }

  return NextResponse.json({ received: true });
}

Testing

Local development

Hooked can only reach public HTTPS URLs, so expose your local server with a tunnel such as ngrok:

ngrok http 3000
# Use the https://....ngrok-free.app URL as your webhook

You can also point the webhook at a request inspector like webhook.site to see the exact payloads.

Send yourself a test payload

Sign a sample body with your secret the same way Hooked does:

BODY='{"status":"COMPLETED","message":"Video completed","data":{"videoId":"test_video","projectId":"test_project","status":"COMPLETED","url":"https://example.com/video.mp4","metadata":{"userId":"u_42"}}}'
T=$(date +%s)
SIG=$(printf '%s' "$T.$BODY" | openssl dgst -sha256 -hmac "$HOOKED_WEBHOOK_SECRET" -hex | sed 's/^.* //')

curl -X POST "http://localhost:3000/hooks/hooked" \
  -H "Content-Type: application/json" \
  -H "Hooked-Event: video.completed" \
  -H "Hooked-Delivery: dlv_test" \
  -H "Hooked-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

Common issues

The webhook never arrives

Check the URL is https://, public, and does not redirect.
Make sure your endpoint answers 2xx within 10 seconds.
Check your server logs for three quick attempts close together: that means it answered with an error.
Poll GET /v1/project/{projectId}: if the project is still processing, there is nothing to send yet.

The signature does not match

Verify the raw body. Frameworks that parse JSON first (for example express.json()) change the bytes.
Use the right secret: the Signing secret for the webhook URL in your requests, the endpoint’s own secret for a team endpoint.
After a Rotate, the old secret stops working at once.
Check your server clock: calls more than 5 minutes off are rejected by the snippets above.

The same payload arrives more than once

Your endpoint answered late or with an error and Hooked retried. Deduplicate on videoId / projectId.

The download link stopped working

Links can expire. Call GET /v1/project/{projectId} and use video.url for a fresh one.

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

How it works

URL requirements

Payloads

Headers and events

Video completed

Render failed or timed out

Project failed before it had a video

Fields

Media webhooks

Retries

Verify the signature

Where to find the secret

How the signature is built

Node.js

Python

Extra checks

Implementing an endpoint

Node.js (Express)

Python (FastAPI)

Next.js route handler

Testing

Local development

Send yourself a test payload

Common issues

Next steps

Error Handling

Best Practices

​Overview

​How it works

​URL requirements

​Payloads

​Headers and events

​Video completed

​Render failed or timed out

​Project failed before it had a video

​Fields

​Media webhooks

​Retries

​Verify the signature

​Where to find the secret

​How the signature is built

​Node.js

​Python

​Extra checks

​Implementing an endpoint

​Node.js (Express)

​Python (FastAPI)

​Next.js route handler

​Testing

​Local development

​Send yourself a test payload

​Common issues

​Next steps

Error Handling

Best Practices

Overview

How it works

URL requirements

Payloads

Headers and events

Video completed

Render failed or timed out

Project failed before it had a video

Fields

Media webhooks

Retries

Verify the signature

Where to find the secret

How the signature is built

Node.js

Python

Extra checks

Implementing an endpoint

Node.js (Express)

Python (FastAPI)

Next.js route handler

Testing

Local development

Send yourself a test payload

Common issues

Next steps