Language: EN
Start free

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
Events

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.

EventSent when
job.succeededA job delivered its image. data.job lists the output asset ids; download them with your API key.
job.failedA job ended without an image. data.job.failure_code says why; the job's credits are returned.
job.canceledA queued or running job was cancelled, by you or because an earlier step of its chain failed; its credits are returned.
batch.completedEvery job of a batch or chain has finished. data.batch counts the succeeded, failed and cancelled jobs.
webhook.testYou called POST /api/v1/webhooks/{id}/test or used the test button in the app.
Payload

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
      }
    }
  }
}
Signature

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

Delivery

Retries, time limits and caps

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

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.
CallWhat it does
GET /api/v1/webhooksWebhook endpoints of the workspace
POST /api/v1/webhooksCreate 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}/testQueue a signed webhook.test event to the endpoint
POST /api/v1/webhooks/{id}/rotateNew signing secret (returned once); the previous secret keeps signing for 24 hours
GET /api/v1/webhooks/{id}/deliveriesDeliveries to the endpoint, newest first, with status, attempts and the next retry time
POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliverSend the same event (same webhook-id) again; the retry schedule starts over
Questions

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
Get started

Your next collection, shot this week.

20 credits at sign-up, no card required. Images made with free credits carry a watermark. Herofab also removes the watermark from those images once credits are purchased.