> Garmo API docs as Markdown. This page: https://garmo.studio/api/docs/webhooks/ · All docs in one file: https://garmo.studio/api/docs/llms-full.txt

# 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.

```
{
  "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)
```

```
import crypto from "node:crypto";

export function verify(secret, headers, body /* raw string */) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64");
  return headers["webhook-signature"].split(" ").some(s => {
    const sig = s.split(",")[1] || "";
    return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  });
}
```

```
 300) return false;
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
    foreach (explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '') as $part) {
        if (hash_equals($expected, explode(',', $part, 2)[1] ?? '')) return true;
    }
    return false;
}
```

## 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.
