Guide · 8 min read
Run jobs in the background
Pass webhook_url. We POST the same job object as GET /v2/jobs/{id}. Verify the HMAC signature.
Long jobs should not sit in a request timeout. Create the job with webhook_url set to an HTTPS endpoint you control. We POST the same JSON as GET /v2/jobs/{id} and retry failed deliveries on a backoff.
The JSON is a v2 job: id (gen_18402), object, status, model, input, output.url, error, and cost.usd. Verify X-Goonify-Signature with verify_webhook in Python or verifyWebhookAsync in TypeScript. Reject timestamps older than 5 minutes.
A fire-and-forget create call, plus a signed JSON POST when the GPU finishes.
Steps
- 1
Create the job with webhook_url set to your HTTPS endpoint.
- 2
Receive the same JSON object as GET /v2/jobs/{id}.
- 3
Verify X-Goonify-Signature with the dashboard signing secret.
- 4
Return HTTP 2xx. Failed attempts retry on a backoff.
Install the SDK
pip install "goonify @ git+https://github.com/Goonify/goonify.git#subdirectory=sdks/python"Modelgoonify/cnidia
from goonify import Goonify, verify_webhook
client = Goonify()
job = client.jobs.create(
model="goonify/cnidia",
input={"prompt": "a woman in a dim hotel corridor, cinematic"},
webhook_url="https://example.com/goonify/webhook",
)
print(job.id, job.status)
# Incoming POST body is the same object as GET /v2/jobs/{id}:
# {
# "id": "gen_18402",
# "object": "job",
# "status": "completed",
# "model": "goonify/cnidia",
# "input": {"prompt": "..."},
# "output": {"url": "https://cdn.goonify.ai/..."},
# "error": null,
# "cost": {"usd": 0.05}
# }
def handle(body: bytes, signature: str, secret: str) -> None:
verify_webhook(body, signature, secret)What it looks like
Run it with a sandbox key
Sandbox keys return example media and spend nothing. Switch to a live key when you are ready.
