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);
});
}
import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
msg_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
if abs(time.time() - int(timestamp)) > 300: # older or newer than 5 minutes
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
# Two signatures are sent for 24 hours after a secret rotation: accept either.
return any(
part.startswith("v1,") and hmac.compare_digest(part[3:], expected)
for part in headers["webhook-signature"].split(" ")
)
<?php
function herofab_verify(string $secret, array $headers, string $raw_body): bool {
$id = $headers['webhook-id'];
$timestamp = $headers['webhook-timestamp'];
if (abs(time() - (int) $timestamp) > 300) return false; // older or newer than 5 minutes
$key = base64_decode(substr($secret, strlen('whsec_')));
$expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$raw_body", $key, true));
foreach (explode(' ', $headers['webhook-signature']) as $part) {
if (str_starts_with($part, 'v1,') && hash_equals($expected, substr($part, 3))) return true;
}
return false;
}
Scheme: Standard Webhooks specification, checked 30 October 2026 — github.com/standard-webhooks
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.
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.