Skip to content
API PlatformDevelopers
POST/v1/webhooks/endpointsstable

Create 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
Delete the endpoint.

Starts sending the chosen events to your URL. The response contains the signing secret, shown only this once — store it; you need it to check signatures. Lost it? Rotate it.

Try it

Body

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

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

A note for your team.

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.

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

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
Turns test mode off for this page only. It switches back when you leave the page.

Code and response

curl -X POST 'https://mcp.wa-api.cloud/v1/webhooks/endpoints?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://hooks.example.com/incoming",
  "event_type_ids": [
    "contact.created/1",
    "conversation.closed/1"
  ],
  "description": "Order system"
}'

The code reads your key from $API_KEY.

Body

Body fields
FieldTypeWhat it is
urlrequiredstringA public https URL. Private and local addresses are refused.1–2048 characters
event_type_idsrequiredarray of stringEvent type ids with version, e.g. contact.created/1.1–200 itemsSigned in? Pick one from your data with “My data”.
descriptionstringA note for your team.0–500 characters
custom_headersobjectExtra 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_formatstringenvelope (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 · default "envelope"

Headers

Headers
FieldTypeWhat it is
AuthorizationrequiredheaderBearer $API_KEY — your API key.
Api-VersionheaderThe 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-KeyrequiredheaderRequired here. Any unique string (8–128 characters), e.g. your order id plus the step. Kept 24 hours. Not needed with dry_run=true.pattern ^[A-Za-z0-9._:-]+$ · 8–128 characters

Response 201

The endpoint and its signing secret (once).

Response fields
FieldTypeWhat it is
endpointrequiredobject
idrequiredstring
urlrequiredstring
descriptionrequiredstring or null
statusrequiredstringactive | disabled | paused
custom_headersrequiredobjectCustom header names; values masked to the last 4 characters.
consecutive_failuresrequirednumber
disabled_atrequiredstring or null
disabled_reasonrequiredstring or null
signing_secretrequiredstringAlways masked. The secret is shown once, on create or rotate.
payload_formatrequiredstring"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_atrequiredstring or null
updated_atrequiredstring or null
subscriptionsobject or null
countrequirednumber
all_activerequiredboolean
event_typesrequiredarray of object
signing_secretrequiredstring
warningrequiredstring
dry_runbooleantrue when this was a dry run: every check ran and nothing changed.

Errors

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

StatusCodeWhen
400invalid_input

A field is missing or has the wrong format. errors[] points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.

401unauthenticated

The Authorization header is missing, the key is unknown, expired or revoked.

403entitlement_required

The workspace's plan does not include API access (api_access).

403insufficient_scope

The key does not have the permission this operation needs.

409conflict

Also returned while a request with the same Idempotency-Key is still running.

429rate_limited

The key or workspace went over its rate limit. Wait for Retry-After seconds.

503upstream_unavailable

A service behind the API is briefly unavailable. Safe to retry with backoff.

504timeout

The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

Receive new contacts and closed conversations

Request body

{
  "url": "https://hooks.example.com/incoming",
  "event_type_ids": [
    "contact.created/1",
    "conversation.closed/1"
  ],
  "description": "Order system"
}

Response 201

{
  "endpoint": {
    "id": "ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA",
    "url": "https://hooks.example.com/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
  },
  "signing_secret": "whsec_EXAMPLE_not_a_real_secret_000000000000",
  "warning": "Store this secret now. It will not be shown again."
}

Operation path

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