Webhooks

Add webhook_url (https, a public address) to an edit request and Garmo POSTs the job there when it ends, so you never have to poll.

The event

type is job.completed, job.failed or job.canceled; data is the job exactly as GET /jobs/{id} returns it, including your metadata.

POST to your webhook_url
{
  "id": "evt_1842a7c9e3ea2b51",
  "type": "job.completed",
  "created_at": "2026-11-19T14:02:59Z",
  "data": {
    "id": "job_8Kq2xV7mPz4LtR9wNc3B",
    "object": "job",
    "tool": "color",
    "status": "completed",
    "livemode": true,
    "outputs": [
      {
        "id": "out_1",
        "status": "succeeded",
        "label": "dress · terracotta",
        "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…0.webp?X-Amz-Signature=…",
        "url_expires_at": "2026-11-20T14:00:00Z"
      }
    ],
    "credits_charged": 1,
    "credits_refunded": 0,
    "metadata": {
      "sku": "DR-123"
    },
    "created_at": "2026-11-19T14:02:11Z",
    "completed_at": "2026-11-19T14:02:58Z"
  }
}

Verify the signature

Webhooks are signed the Standard Webhooks way with the webhook secret of the key that made the job (whsec_…, shown on the API page, one per key). Three headers come with each request:

  • webhook-id: the same on every retry of one delivery; use it to drop repeats.
  • webhook-timestamp: Unix seconds. Refuse anything older than five minutes.
  • webhook-signature: v1, plus the base64 HMAC-SHA256 of id.timestamp.body, keyed with the base64-decoded part of the secret after whsec_.

Verify against the raw body, before parsing JSON. The official Standard Webhooks libraries work as they are.

import base64, hashlib, hmac, time

def verify(secret: str, headers, body: bytes) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(expected, s.split(",", 1)[1])
               for s in headers["webhook-signature"].split() if "," in s)

Answers and retries

Answer with any 2xx within 3 seconds; do the work after answering. Anything else, a timeout or a redirect counts as failed and the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After that it stops; the job is always available with GET /jobs/{id}.

The webhook address is checked on every try: it must be https and resolve to a public address. Redirects are not followed.