---
title: "Update a webhook endpoint"
method: PUT
path: "/api/v1/webhook-endpoints/{id}"
tags: ["Webhooks"]
---

# Update a webhook endpoint

`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`

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.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- EndpointRequest: Webhook endpoint create/update payload
  - `url` string: 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.
  - `events` string[]: 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`.
  - `description` string: Free-text label shown in listings
  - `enabled` boolean: Update only — ignored on create, where an endpoint starts enabled. `false` pauses deliveries; `true` resumes them and clears an automatic disable.

## Response `200`

The endpoint as it now is

## Other responses

- `400`: - `invalid_param` on `url` — too long, not `https://`, a port other than 443, no host, or the host does not resolve to a public address (loopback, private, link-local and the other non-public ranges are refused) - `invalid_param` on `events` — a type that is not a subscribable event; `details.received` is the one refused - `invalid_param` on `description` — too long
- `404`: `not_found` — no webhook endpoint with this id on your account
- `409`: Conflict — `error.code` is `idempotency_key_reuse` (the key already means a different request) or `request_in_progress` (the first request under this key has not settled yet; retryable).
- `429`: Rate limited — `error.code` is `rate_limited` and `retryable` is true. `Retry-After` says how many seconds to wait.

---

[API](https://skmtc.dev/imagestep/apis/imagestep-api.md) · [All operations](https://skmtc.dev/imagestep/apis/imagestep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imagestep/apis/imagestep-api/revisions/5e8e922a3085?raw)