PUT/v1/webhooks/endpoints/{endpoint_id}/subscriptionsbeta

Set subscriptions

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 list back.

Replaces the full list of events an endpoint receives: types you leave out are unsubscribed. Read the current list with Get an endpoint first.

Try it

Path

endpoint_idrequiredstring

The endpoint id.

Edit as JSON

event_type_idsrequiredlist

Event type ids with version, e.g. `contact.created/1`.

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 PUT 'https://mcp.wa-api.cloud/v1/webhooks/endpoints/ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA/subscriptions?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "event_type_ids": [
    "conversation.created/1",
    "conversation.assigned/1",
    "conversation.closed/1"
  ]
}'

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
event_type_idsrequired	array of string	Event type ids with version, e.g. `contact.created/1`.1–200 itemsSigned in? Pick one from your data with “My data”.

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 new set.

Response fields
Field	Type	What it is
endpoint_idrequired	string
subscriptionsrequired	array of object
idrequired	string
event_type_idrequired	string
event_type_namerequired	string
versionrequired	string or null
created_atrequired	string or null
addedrequired	array of string
removedrequired	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

Listen to conversation events

Request body

{
  "event_type_ids": [
    "conversation.created/1",
    "conversation.assigned/1",
    "conversation.closed/1"
  ]
}

Response 200

{
  "endpoint_id": "ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA",
  "subscriptions": [
    {
      "id": "sub_01J8Z6Q5A1B2C3D4E5F6G7H8J9",
      "event_type_id": "conversation.created/1",
      "event_type_name": "conversation.created",
      "version": "1",
      "created_at": "2026-09-24T10:00:00Z"
    }
  ],
  "added": [
    "conversation.created/1",
    "conversation.assigned/1"
  ],
  "removed": [
    "contact.created/1"
  ]
}

Operation path

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