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 withGET /v1/webhooks/jobs/secret(needswebhooks: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
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
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
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:
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":{}}'gets400; 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
5xxmakes Windpaint send the samewebhook-idagain;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 rejectshttp://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.