Windpaint
Recipes

Webhook receiver

A FastAPI service that verifies signed job and workflow run webhooks, saves the outputs exactly once, and catches anything whose webhook never arrived.

When you submit a job or start a workflow run with webhook_url, Windpaint POSTs its status to that URL when it finishes. This recipe builds a receiver for those calls: it verifies the signature, answers immediately, downloads the outputs once per job or run, and runs a slow reconcile loop for anything whose webhook never got through.

Deliveries are signed with your organization’s signing secret (Standard Webhooks) and retried for about six hours when your endpoint doesn’t answer 2xx. So the receiver can trust a verified body as the job’s status at the time of the event. It still has to cope with duplicates (a retry after a lost 2xx), out-of-order events, and a delivery that gives up because your endpoint was down for longer than the retry window.

Prerequisites

  • An API key exported as WINDPAINT_API_KEY (API keys).

  • The signing secret exported as WINDPAINT_WEBHOOK_SECRET. Read it with GET /v1/webhooks/jobs/secret (needs webhooks:update), or copy it from Settings → Webhooks → Request webhooks:

    curl -s https://api.windpaint.ai/v1/webhooks/jobs/secret \
      -H "Authorization: Bearer $WINDPAINT_API_KEY" | jq -r .secret.secret
    
  • Python 3.10+ with pip install fastapi uvicorn httpx standardwebhooks.

  • A tunnel for local testing: cloudflared or ngrok. Production webhook URLs must be https://.

The code

Three files: a small SQLite store shared by both sides, the receiver, and a submit script.

store.py: track every job and run

store.py
import sqlite3

db = sqlite3.connect("jobs.db", isolation_level=None, check_same_thread=False)
db.execute(
    """CREATE TABLE IF NOT EXISTS work (
        id         TEXT PRIMARY KEY,   -- request_id or run id
        kind       TEXT NOT NULL,      -- request | run
        state      TEXT NOT NULL,      -- pending | processing | completed | failed | nsfw | canceled | error
        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
    )"""
)
db.execute("CREATE TABLE IF NOT EXISTS deliveries (id TEXT PRIMARY KEY)")


def record_pending(id: str, kind: str) -> None:
    db.execute("INSERT OR IGNORE INTO work (id, kind, state) VALUES (?, ?, 'pending')", (id, kind))


def first_delivery(delivery_id: str) -> bool:
    """True the first time a webhook-id is seen."""
    return db.execute("INSERT OR IGNORE INTO deliveries (id) VALUES (?)", (delivery_id,)).rowcount == 1


def claim(id: str, kind: str) -> bool:
    """Atomically take a job or run for processing. False if it's done or someone else has it."""
    record_pending(id, kind)
    cursor = db.execute(
        "UPDATE work SET state = 'processing', updated_at = datetime('now') "
        "WHERE id = ? AND state IN ('pending', 'error')",
        (id,),
    )
    return cursor.rowcount == 1


def finish(id: str, state: str) -> None:
    db.execute("UPDATE work SET state = ?, updated_at = datetime('now') WHERE id = ?", (state, id))


def pending_older_than(seconds: int) -> list[tuple[str, str]]:
    rows = db.execute(
        "SELECT id, kind FROM work WHERE state IN ('pending', 'error') "
        "AND updated_at < datetime('now', ?)",
        (f"-{seconds} seconds",),
    )
    return list(rows)

first_delivery() drops repeats of the same delivery. claim() is what keeps the outputs from being saved twice: only one caller can move a job from pending to processing, so a retried delivery and the reconcile loop can’t both download them.

app.py: the receiver

app.py
import asyncio
import mimetypes
import os
from contextlib import asynccontextmanager
from pathlib import Path

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

import store

API = os.environ.get("WINDPAINT_API_URL", "https://api.windpaint.ai").rstrip("/") + "/v1"
KEY = os.environ["WINDPAINT_API_KEY"]
WEBHOOK = Webhook(os.environ["WINDPAINT_WEBHOOK_SECRET"])
OUT = Path("outputs")
OUT.mkdir(exist_ok=True)
TERMINAL = {"completed", "failed", "nsfw", "canceled"}


def api() -> httpx.AsyncClient:
    return httpx.AsyncClient(base_url=API, headers={"Authorization": f"Bearer {KEY}"}, timeout=60)


async def download(client: httpx.AsyncClient, asset_id: str, content_type: str, name: str) -> None:
    signed = await client.get(f"/generation/assets/{asset_id}/url")
    signed.raise_for_status()
    url = signed.json()["data"]["url"]
    async with httpx.AsyncClient(timeout=300) as plain:  # no Authorization on signed URLs
        media = await plain.get(url)
        media.raise_for_status()
    ext = mimetypes.guess_extension(content_type) or ""
    (OUT / f"{name}{ext}").write_bytes(media.content)


async def process(kind: str, status: dict) -> None:
    """Save a finished job's or run's outputs. `status` is the webhook's data or a fresh GET."""
    id = status["request_id"] if kind == "request" else status["id"]
    if status["status"] not in TERMINAL:
        return  # a started event, or a poll that came too early
    if not store.claim(id, kind):
        return  # already handled, or being handled
    try:
        async with api() as client:
            if status["status"] == "completed" and kind == "request":
                for i, output in enumerate(status["outputs"]):
                    await download(client, output["id"], output["content_type"], f"{id}-{i}")
            elif status["status"] == "completed":
                for name, files in status["outputs"].items():
                    for i, output in enumerate(files):
                        await download(client, output["id"], output["content_type"], f"{id}-{name}-{i}")
        print(f"{kind} {id}: {status['status']} ({status.get('error_code') or 'ok'})")
        store.finish(id, status["status"])
    except Exception:
        store.finish(id, "error")  # picked up again by the reconcile loop
        raise


async def reconcile_forever() -> None:
    """Catch work whose webhook never got through, for example while this service was down."""
    while True:
        await asyncio.sleep(300)
        for id, kind in store.pending_older_than(600):
            path = f"/generation/requests/{id}/status" if kind == "request" else f"/workflows/runs/{id}"
            try:
                async with api() as client:
                    response = await client.get(path)
                    response.raise_for_status()
                    body = response.json()
                await process(kind, body["data"] if kind == "run" else body)
            except Exception as exc:
                print(f"{kind} {id}: reconcile failed: {exc!r}")


@asynccontextmanager
async def lifespan(app: FastAPI):
    task = asyncio.create_task(reconcile_forever())
    yield
    task.cancel()


app = FastAPI(lifespan=lifespan)


@app.post("/windpaint/webhook")
async def webhook(request: Request, background: BackgroundTasks) -> Response:
    raw = await request.body()
    try:
        # Checks the signature against the raw body and rejects timestamps over 5 minutes old.
        event = WEBHOOK.verify(raw, dict(request.headers))
    except WebhookVerificationError:
        return Response(status_code=400)
    if store.first_delivery(request.headers["webhook-id"]):
        kind = event["type"].split(".", 1)[0]  # "request" or "run"
        background.add_task(process, kind, event["data"])
    # Answer within the 10 s timeout; do the work after responding.
    return Response(status_code=204)

The handler acts only on a verified body, and decides from data.status, not from the event type or the order deliveries arrive in. A started event (if you subscribe to it) is ignored here because it isn’t terminal.

submit.py: submit a job or start a run with webhook_url

submit.py
import os
import sys
import uuid

import httpx

import store

API = os.environ.get("WINDPAINT_API_URL", "https://api.windpaint.ai").rstrip("/") + "/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['WINDPAINT_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),  # safe to retry this exact call
}

if sys.argv[1] == "run":
    response = httpx.post(
        f"{API}/workflows/text-to-clip/runs",
        headers=HEADERS,
        json={"inputs": {"idea": sys.argv[2]}, "webhook_url": os.environ["WEBHOOK_URL"]},
        timeout=60,
    )
    response.raise_for_status()
    run = response.json()["data"]
    store.record_pending(run["id"], "run")
    print(f"started run {run['id']}")
else:
    response = httpx.post(
        f"{API}/generation/capabilities/image.generate",
        headers=HEADERS,
        json={"prompt": sys.argv[1], "aspect_ratio": "16:9", "webhook_url": os.environ["WEBHOOK_URL"]},
        timeout=60,
    )
    response.raise_for_status()
    job = response.json()
    store.record_pending(job["request_id"], "request")  # the reconcile loop now owns this job too
    print(f"submitted {job['request_id']} ({job['credits_estimate']} credits held)")

Recording the job at submit time is what lets the reconcile loop find it if the webhook never gets through. In your own app, this is the row you already store next to the user’s request. The Idempotency-Key means a retry of the same POST after a timeout returns the first job instead of creating a second; see Idempotency.

Test it locally

Start the receiver

export WINDPAINT_API_KEY=aak_...
export WINDPAINT_WEBHOOK_SECRET=whsec_...
uvicorn app:app --port 8000

Expose it over https

In a second terminal, with either tool:

cloudflared
cloudflared tunnel --url http://localhost:8000
# prints https://<random-words>.trycloudflare.com

Submit a job and start a run

In a third terminal, from the same directory (so it shares jobs.db):

export WINDPAINT_API_KEY=aak_...
export WEBHOOK_URL=https://<your-tunnel-host>/windpaint/webhook
python submit.py "a paper boat on a rain-soaked street, reflections, night"
python submit.py run "a paper boat drifting down a rain-soaked street at night"

A few seconds later the receiver logs:

INFO:     34.x.x.x:0 - "POST /windpaint/webhook HTTP/1.1" 204 No Content
request 7c1e9a02-...: completed (ok)

and the image is in outputs/. The run’s webhook arrives when the clip is done, a few minutes later.

Check the failure paths

  • Forged call: curl -X POST "$WEBHOOK_URL" -H 'Content-Type: application/json' -d '{"type":"request.completed","data":{}}' gets 400; there’s no valid signature.
  • Endpoint down: stop uvicorn, submit a job, and start uvicorn again a minute later. The delivery is retried (about 5 s, 30 s, 2 min after the first attempt) and the output is saved when it gets through. GET /v1/webhooks/jobs/deliveries?request_id=<id> shows each attempt.
  • Duplicate: answering slowly or with 5xx makes Windpaint send the same webhook-id again; first_delivery() drops it.

Tunnel URLs change each time you restart the tunnel. A job carries the webhook_url it was submitted with, so jobs submitted against an old tunnel URL are only picked up by the reconcile loop.

When the webhook fires

With the default webhook_events (["completed"]), one delivery per job or run when it reaches a final status: completed, failed, nsfw or canceled for jobs, completed, failed or canceled for runs. Add "started" to webhook_events to also hear when it starts. See Job webhooks.

In production

  • Serve the receiver over https://. Production rejects http:// webhook URLs at submit, and never calls a URL that resolves to a private address.
  • Verify against the raw body. Parsing and re-serializing the JSON changes the bytes and breaks the signature.
  • Rotate the secret with POST /v1/webhooks/jobs/secret/rotate. The old secret keeps signing alongside the new one for 24 hours by default, and the library accepts a match on either entry, so deploy the new secret inside that window.
  • Swap SQLite for your database. Keep the conditional update in claim(): it’s what keeps two workers from processing the same job.
  • Keep the reconcile loop, at a slow interval. It catches a delivery that failed for good, for example after your endpoint was down for longer than the six-hour retry window.
  • Download outputs you need to keep. Assets are deleted when your organization’s retention period ends, 7 days by default. Or store asset ids if you only need the outputs while they’re kept; see Media in your app.

Next steps