Webhooks

Register an https:// URL and the service POSTs signed events to it when a job finishes — the automation's answer to "tell me when it is done", where a terminal's is --wait. Up to 10 endpoints per account. This page follows a receiver from registering it to verifying what arrives, handling each event, and what happens when it does not answer.

Registering an endpoint

Name the URL and the events it wants. Leave events out for every job-level event; the per-item ones are opt-in by name, because a 500-item job would otherwise turn one registration into 500 deliveries nobody asked for. The URL must be https:// on port 443 and resolve to a public address — where an endpoint may point has the whole rule.

const endpoint = await client.webhooks.create({"url":"https://example.com/hooks/imagestep","events":["job.completed","job.failed"],"description":"prod"});
console.log(endpoint.secret); // store it now — it is not shown again

endpoint = client.webhooks.create("https://example.com/hooks/imagestep", events=["job.completed","job.failed"], description="prod")
print(endpoint["secret"])  # store it now — it is not shown again

imagestep webhook create --url https://example.com/hooks/imagestep --events job.completed,job.failed --description prod -o json

curl -s https://api.imagestep.dev/api/v1/webhook-endpoints -H "Authorization: ApiKey $IMAGESTEP_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/imagestep","events":["job.completed","job.failed"],"description":"prod"}'

The answer — 201, and the only response that ever carries secret:

{
  "id": "whe_998fed6d72bd4b9bb5fbd66ed386b516",
  "url": "https://example.com/hooks/imagestep",
  "description": "prod",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "enabled": true,
  "createdAt": "2026-09-17T16:25:57.144262013Z",
  "updatedAt": "2026-09-17T16:25:57.144262013Z",
  "consecutiveFailures": 0,
  "secret": "whsec_HU55buvTtDgrSzg4rJgs5CGS5xG-Bz7VAS1sdiaYKzQ",
  "secretHint": "whsec_H…YKzQ"
}

The signing secret is returned once, by create and by POST /webhook-endpoints/{id}/rotate-secret; every read shows a masked secretHint. A lost secret is rotated, not recovered, and there is no overlap: every attempt after a rotation — retries of earlier events included — is signed with the new secret, so deliveries fail verification until your receiver has it, and are retried rather than lost. The n8n trigger registers an endpoint for you when the workflow is activated.

Then send it a webhook.test event and read what your receiver answered. It is one attempt, made now and never retried — its answer is the response — and it works on a disabled endpoint, which is how you check a fixed receiver before turning it back on:

const delivery = await client.webhooks.test("<endpoint-id>"); // { status, responseStatus, error, … }

delivery = client.webhooks.test("<endpoint-id>")  # {"status", "responseStatus", "error", …}

imagestep webhook test <endpoint-id>   # exits 1 unless the receiver answered 2xx

curl -s -X POST https://api.imagestep.dev/api/v1/webhook-endpoints/<endpoint-id>/test -H "Authorization: ApiKey $IMAGESTEP_API_KEY"

Verifying a delivery

Every delivery is a POST of the event as JSON, with these headers:

ImageStep-Signature: t=1757318400,v1=185cd63a1256266ee9b63b641e768f5c75223ebc27d19d9aaa89414568990e32
ImageStep-Event-Id: evt_4d5b552267e64eef916ed3f45f9cf260
ImageStep-Event-Type: job.completed
ImageStep-Attempt: 1

v1 is HMAC-SHA256("<t>.<raw request body>", secret) in lowercase hex — the same construction Stripe uses, so an existing verifier ports over. The key is the secret exactly as you were given it, the whsec_ prefix included, as UTF-8 bytes; nothing is base64-decoded. A receiver does three things:

1. Takes the raw body, before any JSON parsing — re-serialising changes bytes, and the MAC with them.
2. Recomputes v1 from t, the body and the secret, and compares in constant time.
3. Rejects a t outside its tolerance — 300 s is typical, and the SDKs' default. t is when this attempt was signed, not when the event happened: every retry is signed afresh, so the window never turns away a late retry, only a captured delivery replayed later.

Both SDKs do all three:

import { constructWebhookEvent } from "imagestep";

export async function POST(request) {
  const raw = await request.text();                                   // the raw body, not request.json()
  let event;
  try {
    event = await constructWebhookEvent(raw, request.headers.get("ImageStep-Signature"), secret);
  } catch {
    return new Response("bad signature", { status: 400 });
  }
  if (event.type === "job.completed") await collect(event.data);      // an error here is a 500, and a retry
  return new Response(null, { status: 204 });
}

from imagestep import WebhookSignatureError, construct_webhook_event

def handle(raw_body: bytes, signature: str | None, secret: str) -> int:
    try:
        event = construct_webhook_event(raw_body, signature, secret)
    except WebhookSignatureError:
        return 400
    if event["type"] == "job.completed":
        collect(event["data"])
    return 204

A receiver in a language with no SDK — Go, PHP, a Code node in a workflow tool — ports these dozen lines. All three steps are in them:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body as a string, exactly as it arrived — before any JSON.parse
export function verifyImageStepSignature(rawBody, header, secret, { toleranceSeconds = 300, now = Date.now() / 1000 } = {}) {
  if (!secret) throw new Error("no webhook secret configured"); // an empty key's HMAC is one anybody can compute
  const parts = Object.fromEntries(String(header || "").split(",").map((kv) => kv.trim().split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || !parts.v1) return false;
  if (Math.abs(now - timestamp) > toleranceSeconds) return false; // stale — or from the future
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1.toLowerCase());
  return given.length === expected.length && timingSafeEqual(given, Buffer.from(expected)); // constant time
}

import hashlib
import hmac
import time

# raw_body: the request body as bytes, exactly as it arrived — before any json.loads
def verify_imagestep_signature(raw_body: bytes, header: str | None, secret: str, tolerance_seconds: int = 300, now: float | None = None) -> bool:
    if not secret:
        raise ValueError("no webhook secret configured")  # an empty key's HMAC is one anybody can compute
    parts = dict(kv.strip().split("=", 1) for kv in (header or "").split(",") if "=" in kv)
    try:
        timestamp, given = int(parts["t"]), parts["v1"].lower()
    except (KeyError, ValueError):
        return False
    if abs((time.time() if now is None else now) - timestamp) > tolerance_seconds:
        return False  # stale — or from the future
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)  # constant time

Events

The body is always id · type · createdAt · data, and data is a summary: read GET /api/v1/jobs/{jobId} for the items and outputs. A webhook.test event has only a message in data. A job that finished — job.completed:

{
  "id": "evt_4d5b552267e64eef916ed3f45f9cf260",
  "type": "job.completed",
  "createdAt": "2026-09-17T16:25:57.619594170Z",
  "data": {
    "jobId": "job_6183ee1d2b2b42fd983dbcdc93188ffb",
    "type": "process",
    "status": "COMPLETED",
    "totalItems": 1,
    "completedItems": 1,
    "failedItems": 0,
    "creditsCharged": 0
  }
}

A job with a failed item — job.failed. errorCode and retryable are the job's verdict on its failed items, the same pair GET /jobs/{id} answers with, and what a receiver decides a resume on:

{
  "id": "evt_1816043197354a4ea5de6ec4b81d2aa7",
  "type": "job.failed",
  "createdAt": "2026-09-17T16:25:57.847224878Z",
  "data": {
    "jobId": "job_a7cd6bddfb09450f8bb76999ab28f5e0",
    "type": "process",
    "status": "FAILED",
    "totalItems": 1,
    "completedItems": 0,
    "failedItems": 1,
    "creditsCharged": 0,
    "errorCode": "invalid_param",
    "retryable": false
  }
}

One item that finished — job.item.completed, opt-in:

{
  "id": "evt_f00cfc585ea4426e81ada067bffc2e05",
  "type": "job.item.completed",
  "createdAt": "2026-09-17T16:25:57.615560503Z",
  "data": {
    "jobId": "job_6183ee1d2b2b42fd983dbcdc93188ffb",
    "type": "process",
    "itemIndex": 0,
    "status": "COMPLETED",
    "settledItems": 1,
    "totalItems": 1,
    "resultAssetId": "ast_c2ca0ef3785134a98e41965a98f13cb4",
    "sourceAssetId": "ast_28b79e93a59846e4b8c10e8ec6ef3cf9"
  }
}

One item that failed — job.item.failed, opt-in, with the item's own verdict:

{
  "id": "evt_1aee53a37bd74314b74b1035bc1f7ca5",
  "type": "job.item.failed",
  "createdAt": "2026-09-17T16:25:57.842963670Z",
  "data": {
    "jobId": "job_a7cd6bddfb09450f8bb76999ab28f5e0",
    "type": "process",
    "itemIndex": 0,
    "status": "FAILED",
    "settledItems": 1,
    "totalItems": 1,
    "sourceAssetId": "ast_28b79e93a59846e4b8c10e8ec6ef3cf9",
    "error": "Pipeline processing failed: crop area 100x100 at 5000,5000 does not fit inside the image",
    "errorCode": "invalid_param",
    "retryable": false
  }
}

What each key of data is, and which events carry it:

Writing the receiver

• Answer 2xx within 10 s, as soon as the event is durably accepted, and do the work afterwards. The connection gets 5 s and the answer 10 s; past either — or on a 3xx (redirects are not followed), a 4xx or a 5xx — the attempt failed and is retried, and a receiver that was merely slow then has the event twice.
• Deduplicate on ImageStep-Event-Id, which is stable across every attempt of one delivery.
• Do not rely on order. One endpoint's deliveries go one at a time, oldest due first, but a retried event arrives after events queued behind it — a job.completed can land before the retry of one of its job.item.completed.
• Treat the payload as a notification, not the data: read GET /api/v1/jobs/{jobId} for the outputs, and publish or download them from there.
• Verify the signature rather than allow-listing addresses: no source-address list is published, and an address would only prove where a request came from, not what it says.

Retries and the audit trail

A delivery is accepted on any 2xx; the body of your answer is not read. The first attempt is made as soon as the event is queued — usually well under a second, at most a few — and a failed one is retried with backoff min(2^(attempt−1) × 1 min, 6 h) until 24 hours after it was queued. That is at most 12 attempts, the last about 20 h 31 min after the first:

Each wait starts when the previous attempt finished, so the clock runs a few seconds behind the table. When the next wait would cross the 24-hour mark, the delivery is closed as FAILED — which is what counts towards auto-disable. Different endpoints are delivered side by side, so a slow receiver delays only its own events.

GET /api/v1/webhook-endpoints/{id}/deliveries is where to look when an event did not arrive — one record per event, newest first, paged like every list:

const { items, meta } = await client.webhooks.deliveries("<endpoint-id>");

page = client.webhooks.deliveries("<endpoint-id>")  # page.items, page.meta

imagestep webhook deliveries <endpoint-id> -o json

curl -s "https://api.imagestep.dev/api/v1/webhook-endpoints/<endpoint-id>/deliveries" -H "Authorization: ApiKey $IMAGESTEP_API_KEY"

One record — the first event above, after a receiver answered 405 to the first attempt. A row says whether the event arrived, not what was in it: eventId is the id of the document your receiver was sent, the same on every retry, so it is what joins the two.

{
  "id": "whd_891caec749664aac9e4b1b5ad09c0669",
  "eventId": "evt_4d5b552267e64eef916ed3f45f9cf260",
  "eventType": "job.completed",
  "status": "PENDING",
  "attempts": 1,
  "createdAt": "2026-09-17T16:25:57.619625Z",
  "nextAttemptAt": "2026-09-17T16:26:58.402113Z",
  "responseStatus": 405,
  "error": "HTTP 405"
}

Records are kept 14 days.

Auto-disable and pausing

Retries are per event; the endpoint itself is switched off when 5 consecutive events each ran out of retries — 5 chains of 24 hours each with no 2xx in between. The endpoint's consecutiveFailures is that count, so a monitor can watch it climb. At 5, enabled becomes false, disabledAt and disabledReason (the count and the last error) are set, and the account owner gets one email. Any accepted delivery resets the count, so a receiver with an overnight outage and a working morning is never disabled.

Pausing is the same switch by hand: {"enabled": false}, or imagestep webhook update <id> --disable. Either way a disabled endpoint receives nothing: deliveries still queued for it are closed as FAILED (endpoint disabled), and events that happen while it is off are never queued — nothing is replayed when it comes back, so a receiver catches up by listing its recent jobs (GET /api/v1/jobs, filtered by createdFrom and status). To turn it back on, fix the receiver, check it with a test delivery, then:

const endpoint = await client.webhooks.update("<endpoint-id>", { enabled: true });

endpoint = client.webhooks.update("<endpoint-id>", {"enabled": True})

imagestep webhook update <endpoint-id> --enable

curl -s -X PUT https://api.imagestep.dev/api/v1/webhook-endpoints/<endpoint-id> -H "Authorization: ApiKey $IMAGESTEP_API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": true}'

This PUT is a patch: it changes what you pass and leaves the URL, the events and the secret alone. Turning the endpoint on also clears disabledAt, disabledReason and the count.

Where an endpoint may point

https:// only, on port 443, to a host that resolves to a public address — never a loopback, link-local, private, multicast or unique-local one. The rule is applied at registration, where a URL that breaks it or a host that does not resolve at all is a 400 invalid_param on url, and again immediately before every attempt, against what the host resolves to then: a record re-pointed since is refused on the delivery (target refused: …, no request sent) and retried on the normal schedule in case it flips back. Redirects are not followed. The same address rule guards every URL this service fetches on your behalf — an image from-url, a synchronous url input.

Deliveries leave through an egress that reaches port 443 only, which is why another port is refused at registration — https://example.com:8443/… would otherwise fail every attempt until the endpoint was switched off. The endpoint count is a per-account hard limit (422 resource_limit_exceeded past 10); the other ceilings are on errors, retries & limits.

Managing endpoints

The SDK column is both SDKs, JavaScript above Python. MCP has no webhook tools. The console's /webhooks page is the same list for a person.