Webhooks

Update a webhook endpoint

Every field is optional; only what you send changes. A new url is checked as on create.

  • events: [] goes back to the default subscription, every job-level event.
  • enabled: false pauses the endpoint: nothing new is queued for it, and events already queued are closed as FAILED (endpoint disabled) rather than held.
  • enabled: true turns it back on and also clears an automatic disable — disabledAt, disabledReason and consecutiveFailures. POST /{id}/test is the cheap way to check the receiver first.
put/api/v1/webhook-endpoints/{id}

Request

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

Path parameters

idstring required

The endpoint's id (whe_…), as create and the listing return it

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

The endpoint as it now is

Changes

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