Webhooks
Create a webhook endpoint
POST/webhook-endpoints
Scope webhooks.writeLIVE keys only
Public HTTPS on port 443 only; up to 10 active endpoints per client; no duplicate active URL. The whsec_ secret is shown once. Rotate by creating a replacement and disabling the old endpoint.
Request
Body WebhookEndpointCreateRequest
| Field | Type | Description |
|---|---|---|
urlRequired | string (uri) | Public HTTPS URL on port 443.0–2048 characters |
eventsRequired | array of WebhookEventName | 1–∞ items |
Response
| Status | Meaning |
|---|---|
201 | Created |
The body is { "status": "success", "data": … }. Fields of data (WebhookEndpointCreated):
| Field | Type | Description |
|---|---|---|
endpointRequired | WebhookEndpoint | |
secretRequired | string | whsec_ signing secret. Shown only in this response; store it server-side.Pattern ^whsec_[a-f0-9]{64}$ |
Errors
Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.
| Status | When |
|---|---|
400 | The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed. |
401 | Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked. |
403 | The key lacks the scope, or the operation needs a LIVE key. The key lacks the scope, or this call needs a LIVE key (LIVE_KEY_REQUIRED), or the Business owner is not verified (SENDER_VERIFICATION_REQUIRED). |
409 | Idempotency key reused with another body, or the resource changed state. The idempotency key was used with a different body, a reference is already taken, or the resource changed state. |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |