---
title: "Herofab webhooks: signed job and batch events | Herofab"
description: "Herofab webhook events, payloads and signature checks (Standard Webhooks, HMAC-SHA256) with Node.js, Python and PHP code, retries and delivery limits."
url: https://herofab.app/api/webhooks
language: en
updated: 2026-11-06
---

# Herofab webhooks

Herofab sends a signed POST request to your HTTPS endpoint when a job succeeds, fails or is cancelled and when a whole batch has finished, so an integration does not have to poll. Signatures follow the Standard Webhooks scheme: check the webhook-signature header with the endpoint's whsec\_ secret before trusting the body.

- Standard Webhooks signatures
- 4 event types + test
- 10 attempts over about two days
- Up to 10 endpoints per workspace

## What Herofab sends, and when

Subscribe to some or all of the four events when you create the endpoint; webhook.test is sent only when you ask for it.

| Event | Sent when |
| --- | --- |
| `job.succeeded` | A job delivered its image. data.job lists the output asset ids; download them with your API key. |
| `job.failed` | A job ended without an image. data.job.failure\_code says why; the job's credits are returned. |
| `job.canceled` | A queued or running job was cancelled, by you or because an earlier step of its chain failed; its credits are returned. |
| `batch.completed` | Every job of a batch or chain has finished. data.batch counts the succeeded, failed and cancelled jobs. |
| `webhook.test` | You called POST /api/v1/webhooks/{id}/test or used the test button in the app. |

## A thin event: ids and states

The body carries ids and states only, never image URLs or bytes. Fetch the job or the asset with your API key; the event id is the same on every retry, so use it to ignore duplicates.

```
{
  "id": "evt_3f9c2a7b1d8e4f60a1b2c3d4e5f60718",
  "type": "job.succeeded",
  "created_at": "2026-10-30T12:00:00Z",
  "data": {
    "job": {
      "id": "JOB_ID",
      "tool": "apparel_tryon",
      "state": "succeeded",
      "batch_id": null,
      "failure_code": null,
      "outputs": [
        {
          "asset_id": "OUTPUT_ASSET_ID"
        }
      ]
    }
  }
}

// batch.completed
{
  "id": "evt_…",
  "type": "batch.completed",
  "created_at": "2026-10-30T12:04:00Z",
  "data": {
    "batch": {
      "id": "BATCH_ID",
      "total": 40,
      "counts": {
        "succeeded": 39,
        "failed": 1,
        "canceled": 0
      }
    }
  }
}
```

## Check the signature before anything else

Sign the raw body exactly as received: webhook-id, a full stop, webhook-timestamp, a full stop, then the body, with HMAC-SHA256 keyed by the base64-decoded part of the secret after whsec\_. Compare in constant time and reject timestamps more than five minutes off. The official standardwebhooks packages on npm and PyPI do the same check.

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

// verify.mjs — secret: the whsec_… value returned once when the endpoint was created
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older or newer than 5 minutes
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
  // Two signatures are sent for 24 hours after a secret rotation: accept either.
  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, signature] = part.split(",");
    const given = Buffer.from(signature ?? "", "base64");
    return version === "v1" && given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}
```

Scheme: Standard Webhooks specification, checked 30 October 2026 — [github.com/standard-webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)

## Retries, time limits and caps

| Rule | Value |
| --- | --- |
| Answer | Any 2xx status within 10 seconds acknowledges the event; redirects are not followed |
| Retries | After a failed attempt: 30s, 2m, 10m, 30m, 1h, 3h, 6h, 12h, 24h (10 attempts in all) |
| Failing endpoint | Disabled after 3 days without a successful delivery; the workspace owner is emailed. Enabling it again resets the clock |
| Secret rotation | POST /webhooks/{id}/rotate returns a new secret once; for 24 hours both secrets sign, so the header carries two signatures |
| Endpoints | Up to 10 per workspace; https on a public address, port 80 or 443, at most 2,048 characters |
| Parallel deliveries | At most 2 at a time to one endpoint, so a slow receiver does not hold up the others |
| Test events | Up to 30 an hour |
| Redelivery | POST …/deliveries/{deliveryId}/redeliver sends the same event (same id) again, up to 1,000 times per delivery |
| User-Agent | Herofab-Webhooks/1 |

## Create and manage endpoints

These calls need an API key with the webhooks:write scope. In the Herofab app, the workspace owner and admins manage the same endpoints.

```
curl https://app.herofab.app/api/v1/webhooks \
  -H "Authorization: Bearer $HEROFAB_API_KEY" \
  --json '{"url": "https://example.com/herofab/webhook", "events": ["job.succeeded", "job.failed", "batch.completed"]}'
# → 201 {"object": "webhook_endpoint", "id": "…", "secret": "whsec_…", …}
# The secret is shown only in this response: store it now.
```

| Call | What it does |
| --- | --- |
| `GET /api/v1/webhooks` | Webhook endpoints of the workspace |
| `POST /api/v1/webhooks` | Create a webhook endpoint; the signing secret (whsec\_…) is returned only in this response |
| `GET /api/v1/webhooks/{id}` | Read a webhook endpoint |
| `PATCH /api/v1/webhooks/{id}` | Change url, events or description; enable or disable (enabling resets the failure clock) |
| `DELETE /api/v1/webhooks/{id}` | Delete the endpoint (final); queued deliveries are dropped |
| `POST /api/v1/webhooks/{id}/test` | Queue a signed webhook.test event to the endpoint |
| `POST /api/v1/webhooks/{id}/rotate` | New signing secret (returned once); the previous secret keeps signing for 24 hours |
| `GET /api/v1/webhooks/{id}/deliveries` | Deliveries to the endpoint, newest first, with status, attempts and the next retry time |
| `POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver` | Send the same event (same webhook-id) again; the retry schedule starts over |

## Webhook questions

**What happens if my server is down?**

Herofab retries for about two days on a fixed schedule. Deliveries and their attempts are listed by GET /api/v1/webhooks/{id}/deliveries, and any delivery can be sent again with the redeliver call once the server is back.

**Can the same event arrive twice?**

Yes: a retry after a timeout or a redelivery carries the same webhook-id. Store the ids you have processed and skip repeats.

**Why is there no image URL in the event?**

Events go to an address outside Herofab, so they carry ids only. The image is downloaded with your API key from GET /api/v1/assets/{id}/content, which answers with a short-lived link.

Related

[MCP](https://herofab.app/mcp) · [Privacy notice](https://herofab.app/privacy) · [Bulk product photos script](https://herofab.app/api/guides/bulk-product-photos) · [Shopify product images](https://herofab.app/api/guides/shopify-product-images) · [WooCommerce product images](https://herofab.app/api/guides/woocommerce-product-images) · [API overview: upload, poll, download](https://herofab.app/api)
