Webhooks

Pass webhookUrl to Create a separation job. Use HTTPS in production. Local development may use http://127.0.0.1 or http://localhost; use an HTTPS tunnel when testing a publicly reachable receiver.

A single job can include multiple targets. Gaudio sends one webhook delivery per target when that target reaches a terminal state:completed or failed.

Return any 2xx response within 10 seconds to acknowledge delivery. Do signature verification and enqueue follow-up work, but avoid long processing in the request handler.

Any non-2xx response, timeout, connection failure, or TLS failure is treated as a failed delivery.

Failed deliveries are retried up to 5 times with exponential backoff of about 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours. Retries can arrive more than once or out of order.

Use jobId plus target.model as an idempotency key when updating your own state.

Each delivery includes an X-Gaudio-Signature header. The value is prefixed with sha256=. Compute the HMAC-SHA256 hex digest of the raw request body using your webhook signing secret, add the same prefix, then compare it before trusting the payload.

import hmac
import hashlib
import os
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
secret = os.environ["GAUDIO_WEBHOOK_SIGNING_SECRET"]

@app.post("/gaudio/webhook")
async def receive_webhook(request: Request):
    body = await request.body()
    received = request.headers.get("x-gaudio-signature", "")
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    expected = "sha256=" + expected

    if not hmac.compare_digest(expected, received):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()
    # Enqueue work here; return 2xx quickly so delivery is acknowledged.
    return {"ok": True}