Webhooks

Register a webhook endpoint

Registers an https:// URL to receive job events, and answers 201 with the endpoint.

The response is the only place the signing secret is ever readable (secret). Store it; a lost secret is rotated, not recovered. Every delivery carries ImageStep-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256("<t>.<raw body>", secret): compute it over the raw body, compare in constant time, and reject a t outside your tolerance window.

Omit events, or send [], to receive every job-level event; per-item events are opt-in.

The URL must be on port 443 — the only port deliveries can reach — and resolve to a public address. The address is checked now and again before every delivery attempt, against what the host resolves to then, and redirects are not followed.

post/api/v1/webhook-endpoints

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/webhook-endpoints
  • Auth: API key in header Authorization

Headers

Idempotency-Keystring

Optional. A client-generated unique key (typically a UUID). Same key + the same request (method, path, query string and body) replays the first response verbatim with Idempotency-Replayed: true, without executing again. Same key + a different one returns 409 idempotency_key_reuse. A repeat that arrives while the first is still running returns 409 request_in_progress, which is retryable. Keys are retained 24 hours. At most 255 characters; a longer one is a 400 invalid_param with param: "Idempotency-Key".

Request body

urlstring

Where to POST events: an https:// URL on port 443 whose host resolves to a public address. Required on create; on update, send it only to change it.

eventsstring[]

Event types to receive. Omit it, or send [], for every job-level event (job.completed, job.failed); the per-item events (job.item.completed, job.item.failed) are opt-in, because a 500-item job would otherwise be 500 deliveries nobody asked for. Any other value is 400 invalid_param.

descriptionstring

Free-text label shown in listings

enabledboolean

Update only — ignored on create, where an endpoint starts enabled. false pauses deliveries; true resumes them and clears an automatic disable.

Example request

{
  "url": "https://example.com/hooks/imagestep",
  "description": "Production n8n"
}

Response

Registered and enabled. The one answer that carries secret in the clear.

Changes

No recorded changes to this operation across all 1 revision of this API.