PATCH/v1/webhooks/endpoints/{endpoint_id}beta

Update an endpoint

Needs: Manage webhook endpoints (webhooks:write)
Plan: Any plan with API access
Limits: 60 a minute per key
Dry run: Yes — every check runs with ?dry_run=true, nothing changes
Undo: Send the old values back.

Changes an endpoint's URL, description or custom headers. Fields you leave out stay as they are. To change events, use Set subscriptions.

Try it

Path

endpoint_idrequiredstring

The endpoint id.

Edit as JSON

urloptionalstring

A public https URL. Private and local addresses are refused.

descriptionoptionalstring

`null` clears it.

custom_headersoptionalobject (JSON)

Extra headers sent with every delivery, e.g. your own auth header. Replaces the whole set; `{}` removes all. Names starting `Webhook-` or `Wc-`, and Content-*, Host, User-Agent, Idempotency-Key and Proxy-* are reserved.

payload_formatoptionalstring

`envelope` (recommended): the wrapped body with id, type, version, api_version, occurred_at and data. `data`: only the event data, the older format. Default for endpoints made with this API: `envelope`.

Idempotency-Keyoptional — made for you if empty

Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.

Test mode (dry run): nothing will change

Run liveTurns test mode off for this page only. It switches back when you leave the page.

curl -X PATCH 'https://mcp.wa-api.cloud/v1/webhooks/endpoints/ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://hooks.example.com/v2/incoming"
}'

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
endpoint_idrequired	string · path	The endpoint id.pattern `^ep_[0-9A-HJKMNP-TV-Z]{26}$`Signed in? Pick one from your data with “My data”.

Body

Body fields
Field	Type	What it is
url	string	A public https URL. Private and local addresses are refused.1–2048 characters
description	string or null	`null` clears it.0–500 characters
custom_headers	object	Extra headers sent with every delivery, e.g. your own auth header. Replaces the whole set; `{}` removes all. Names starting `Webhook-` or `Wc-`, and Content-, Host, User-Agent, Idempotency-Key and Proxy- are reserved.
payload_format	string	`envelope` (recommended): the wrapped body with id, type, version, api_version, occurred_at and data. `data`: only the event data, the older format. Default for endpoints made with this API: `envelope`.one of: `data`, `envelope`

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`
Idempotency-Key	header	Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern `^[A-Za-z0-9._:-]+$` · 8–128 characters

Response `200`

The endpoint.

Response fields
Field	Type	What it is
endpointrequired	object
idrequired	string
urlrequired	string
descriptionrequired	string or null
statusrequired	string	active \| disabled \| paused
custom_headersrequired	object	Custom header names; values masked to the last 4 characters.
consecutive_failuresrequired	number
disabled_atrequired	string or null
disabled_reasonrequired	string or null
signing_secretrequired	string	Always masked. The secret is shown once, on create or rotate.
payload_formatrequired	string	"data" = the event's data object as the body; "envelope" = {id, type, version, api_version, occurred_at, company_id, data}.one of: `data`, `envelope`
created_atrequired	string or null
updated_atrequired	string or null
subscriptions	object or null
countrequired	number
all_activerequired	boolean
event_typesrequired	array of object
changedrequired	array of string
dry_run	boolean	`true` when this was a dry run: every check ran and nothing changed.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
404	not_found	No endpoint with this id.
409	conflict	Also returned while a request with the same Idempotency-Key is still running.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.
504	timeout	The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

Move to a new URL

Request body

{
  "url": "https://hooks.example.com/v2/incoming"
}

Response 200

{
  "endpoint": {
    "id": "ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA",
    "url": "https://hooks.example.com/v2/incoming",
    "description": "Order system",
    "status": "active",
    "custom_headers": {
      "X-Hook-Token": "••••9f2a"
    },
    "payload_format": "envelope",
    "consecutive_failures": 0,
    "disabled_reason": null,
    "signing_secret": "whsec_••••••••",
    "created_at": "2026-09-10T12:00:00Z",
    "updated_at": "2026-09-10T12:00:00Z",
    "disabled_at": null
  },
  "changed": [
    "url"
  ]
}

Operation path

The same operation is also at POST /v1/ops/webhooks_update_endpoint, with every field in the JSON body.