Windpaint
Generation

Job webhooks

Get a signed POST when a generation job or workflow run starts or finishes: events, body, signature verification, retries and the signing secret.

Pass a webhook_url when you submit a job or start a workflow run, and Windpaint POSTs the job’s or run’s status to it when it finishes, and optionally when it starts. Every delivery is signed with your organization’s signing secret and retried for about six hours if your endpoint doesn’t answer with a 2xx.

curl -X POST https://api.windpaint.ai/v1/generation/capabilities/video.generate \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "slow dolly in",
    "inputs": {"start_frame": ["8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"]},
    "webhook_url": "https://example.com/hooks/windpaint",
    "webhook_events": ["started", "completed"]
  }'

With the CLI, pass --webhook-url to windpaint run.

Job webhooks are separate from your organization’s account webhooks, which cover account events (members, API keys, support tickets, low balance) and have their own per-endpoint secrets. There are no generation events on account webhooks.

Where you can set it

EndpointFields
POST /v1/generation/capabilities/{capability}webhook_url, webhook_events
POST /v1/generation/models/{model}webhook_url, webhook_events
POST /v1/workflows/{slug}/runswebhook_url, webhook_events
webhook_urlstring

An absolute https:// URL that receives the deliveries.

webhook_eventsstring[]default:["completed"]

Which events to send: started, completed, or both. Needs webhook_url.

These are rejected at submit with 422:

CodeCause
webhook.invalid_urlwebhook_url isn’t an absolute http(s) URL.
webhook.insecure_urlwebhook_url uses http://. Production requires https://.
webhook.unknown_eventswebhook_events is empty or holds a value other than started or completed. details.allowed_events lists the accepted values.
request.validation_failedwebhook_events was sent without webhook_url.

Events

SubscriptionSent whenEvent type
startedA job moves to in_progress, or a run moves to runningrequest.started, run.started
completedA job or run reaches any terminal statusrequest.completed, request.failed, request.nsfw, request.canceled, run.completed, run.failed, run.canceled

completed covers every final status, not only success. A job canceled while it was still queued gets a request.canceled delivery too.

Each event is delivered at most once per job or run (retries of that delivery aside). Events can arrive out of order: a started delivery that is being retried can land after the terminal one. Decide what to do from data.status, not from the order deliveries arrive in.

What’s sent

A POST with Content-Type: application/json and this body:

typestring

The event, for example request.completed or run.failed.

timestampstring

When the event happened (ISO 8601). It stays the same on every retry.

dataobject

For a job, exactly what GET /v1/generation/requests/{id}/status returns. For a workflow run, exactly the run object GET /v1/workflows/runs/{id} returns. It’s the status at the moment of the event.

{
  "type": "request.completed",
  "timestamp": "2026-10-05T14:09:12.874Z",
  "data": {
    "status": "completed",
    "request_id": "3c9a7b1d-2e4f-4a6b-8c0d-1e2f3a4b5c6d",
    "capability": "video.generate",
    "model": "wan-2.2-i2v",
    "project_id": "5b0c7e1a-2f3d-4e5f-8a9b-0c1d2e3f4a5b",
    "source": "api",
    "outputs": [
      {
        "id": "d41e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
        "url": "https://api.windpaint.ai/v1/generation/assets/d41e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a/content",
        "content_type": "video/mp4",
        "width": 848,
        "height": 480,
        "duration_s": 5.0
      }
    ],
    "credits": { "estimate": "4.00", "actual": "4.00" },
    "error": null,
    "error_code": null,
    "created_at": "2026-10-05T14:05:40.120Z",
    "finished_at": "2026-10-05T14:09:12.874Z"
  }
}

The example is shortened. See Read the status for every job field and Runs for the run object.

Headers

Deliveries follow the Standard Webhooks spec:

HeaderValue
webhook-idThe delivery id (UUID). The same on every retry of one event, so use it to de-duplicate.
webhook-timestampUnix seconds when this attempt was sent.
webhook-signatureSpace-separated v1,<signature> entries. Usually one; two while a rotated-out secret is still valid.

Verifying signatures

Each signature is base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{body}")), where body is the raw request body exactly as received and key is the base64-decoded part of your secret after whsec_. Read the secret with GET /v1/webhooks/jobs/secret or from Settings → Webhooks → Request webhooks in the dashboard.

To accept a delivery:

  1. Compute the expected signature from the raw body. Don’t parse and re-serialize the JSON first.
  2. Accept if any v1, entry in webhook-signature matches. Compare in constant time.
  3. Reject if webhook-timestamp is more than 5 minutes from your clock, so a captured request can’t be replayed later.

The official Standard Webhooks libraries do all three with the whsec_ secret as-is.

Python (library)
# pip install standardwebhooks
import os

from standardwebhooks.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["WINDPAINT_WEBHOOK_SECRET"])  # whsec_...


def verify(raw_body: bytes, headers: dict[str, str]) -> dict:
    """Return the parsed body, or raise WebhookVerificationError."""
    return wh.verify(raw_body, headers)

Retries

  • Success is any 2xx within 10 seconds. Redirects are not followed.
  • Retried: connection errors, timeouts, 408, 429 and 5xx.
  • Not retried: any other status, including 3xx and 4xx other than 408 and 429. The delivery is marked failed straight away.
  • Schedule: up to 10 attempts. The waits after attempts 1 to 9 are about 5 s, 30 s, 2 min, 5 min, 15 min, 30 min, 1 h, 2 h and 2 h, each with ±20% jitter, so the last attempt is roughly 6 hours after the first.
  • Retry-After: if your endpoint answers with Retry-After (in seconds) longer than the scheduled wait, Windpaint waits that long instead, up to 1 hour.
  • After the 10th failed attempt the delivery is marked failed and not tried again.

Every retry sends the same body under the same webhook-id, with a new webhook-timestamp and signature.

In production, a webhook_url whose host resolves to a private, loopback, link-local or other non-public address is never called. The delivery fails at once, isn’t retried, and the delivery log shows last_error: "Webhook URL resolves to a non-public address.".

Windpaint doesn’t publish a fixed list of IP addresses that deliveries come from; verify the signature instead of allow-listing addresses.

Handle it safely

  1. Verify the signature on the raw body, and reject stale timestamps.
  2. De-duplicate on webhook-id. A delivery can arrive more than once if your 2xx was lost. Record the ids you’ve processed.
  3. Act on data.status. Deliveries can arrive out of order, and your own fallback poll may have seen the job first.
  4. Answer fast. Return 2xx right away and do slow work (downloading outputs, further jobs) in the background. Each attempt waits at most 10 seconds.

If you keep a list of jobs you’re waiting on, a slow fallback poll for the ones that stay open far too long still helps, for example when your endpoint was down for longer than the retry window.

FastAPI

import os

from fastapi import BackgroundTasks, FastAPI, HTTPException, Request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["WINDPAINT_WEBHOOK_SECRET"])
app = FastAPI()
seen: set[str] = set()  # use your database in production


def handle(event: dict) -> None:
    data = event["data"]
    if event["type"].startswith("run."):
        print("run", data["id"], data["status"])
    elif data["status"] == "completed":
        for out in data["outputs"]:
            print("ready:", out["id"], out["content_type"])
    else:
        print("job", data["request_id"], data["status"], data.get("error_code"))


@app.post("/hooks/windpaint")
async def windpaint_hook(request: Request, background: BackgroundTasks):
    raw = await request.body()
    try:
        event = wh.verify(raw, dict(request.headers))
    except WebhookVerificationError:
        raise HTTPException(status_code=400)
    delivery_id = request.headers["webhook-id"]
    if delivery_id not in seen:
        seen.add(delivery_id)
        background.add_task(handle, event)
    return {"ok": True}

Express

import express from "express";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.WINDPAINT_WEBHOOK_SECRET);
const seen = new Set(); // use your database in production

function handle(event) {
  const data = event.data;
  if (event.type.startsWith("run.")) {
    console.log("run", data.id, data.status);
  } else if (data.status === "completed") {
    for (const out of data.outputs) console.log("ready:", out.id, out.content_type);
  } else {
    console.log("job", data.request_id, data.status, data.error_code);
  }
}

const app = express();

// express.raw keeps the exact bytes the signature covers
app.post("/hooks/windpaint", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(204);
  const deliveryId = req.headers["webhook-id"];
  if (seen.has(deliveryId)) return;
  seen.add(deliveryId);
  handle(event);
});

app.listen(3000);

Webhook receiver in the cookbook builds this out with persistence and downloads.

The signing secret

Your organization has one signing secret for all job and workflow run webhooks. It’s separate from the per-endpoint secrets of account webhooks.

  • Read it with GET /v1/webhooks/jobs/secret. The secret is created the first time it’s read, and you can read it again at any time. Needs webhooks:update.
  • Rotate it with POST /v1/webhooks/jobs/secret/rotate. The old secret keeps signing alongside the new one (a second v1, entry in webhook-signature) for a grace period, 24 hours by default and up to 7 days. Send {"grace_period_seconds": 0} to drop the old secret at once.

To rotate without dropping deliveries: rotate, deploy the new secret to your receiver within the grace period, and keep accepting any matching entry in the meantime.

In the dashboard, Settings → Webhooks → Request webhooks shows the secret masked, with buttons to reveal, copy and rotate it (rotation there uses a 24-hour grace period). Members without webhooks:update see “Signing secret hidden”.

See the Webhooks API reference for the request and response fields.

Delivery log

GET /v1/webhooks/jobs/deliveries lists your organization’s deliveries, newest first, with every attempt’s status code, error and duration and the exact body sent. Filter by request_id or run_id to see what happened to one job’s webhooks. Needs webhooks:read. See the reference.