API Reference

Webhook Endpoints

Create webhook endpoint

Creates a webhook receiver at an absolute HTTP(S) URL; HTTPS is recommended for production. status must be active or inactive. subscribed_events accepts public standard event names or ["*"]; signing_secret is optional, and retry_policy.max_attempts defaults to 3 and accepts 0..5. Call-event access is controlled by workspace is_beta. In beta workspaces, * and empty or omitted subscribed_events include call events; specific lists match only their listed events. Non-beta workspaces may use wildcard subscriptions but never receive call events; explicitly subscribing to call events returns 403 beta_feature_not_enabled. Eligibility is rechecked for every delivery, retry and dead-letter replay; lookup failures do not grant access. Ordinary message.* call records are independent.

POSThttps://api.unifyport.ai/v1/webhook-endpoints

Supported channels

all

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Request parameters

Headers

X-Api-Key
stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type
stringrequired

Use application/json when sending a JSON request body.

Request body

account_id
string

Optional public account ID in the body, e.g. acc_example. On create, binds the endpoint to the account; omission creates a workspace endpoint. On update, only validates the original binding; omission preserves ownership. Cannot switch accounts, convert a workspace endpoint to an account endpoint, or clear the binding. Query input, null, empty or whitespace-only strings, and duplicate fields are invalid. Use exactly account_id; case variants in body or query and ownership mismatches return 400 invalid_request. An explicit account outside the workspace or not found returns 404 account_not_found (20020).

minLength: 1 · pattern: \S

url
stringrequired

Absolute HTTP(S) URL that receives webhook events. Use HTTPS in production.

format: uri

status
stringrequired

Endpoint status: active or inactive.

enum: active, inactive

subscribed_events[]
string[]

Public standard event subscriptions. Omitted, empty, or containing * means all public events, including newly added contact.updated, but not provider.raw_event. Explicitly list event names to receive only selected events.

signing_secret
string

Optional webhook signing secret. Use placeholders in examples.

retry_policy
object

Optional retry settings. max_attempts is the number of retries after the initial request, defaults to 3, and accepts integers from 0 to 5; 0 means initial delivery only.

max_attempts
integer

Retries after the initial delivery, from 0 to 5; 0 means initial delivery only.

Understand the result

A successful configuration request does not prove event delivery. Trigger a relevant event and verify receipt, signature and acknowledgement at your receiver.

Response 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "*"
    ],
    "signing_enabled": true,
    "retry_policy": {
      "max_attempts": 3
    }
  }
}

Response body

id
string

Webhook endpoint identifier (we_...).

account_id
string

Public account ID for an independent account endpoint; omitted for workspace endpoints, never null.

minLength: 1

url
string

Absolute HTTP(S) URL that receives webhook deliveries; HTTPS is recommended for production.

format: uri

status
string

Endpoint status: active or inactive.

enum: active, inactive

subscribed_events[]
string[]

Public standard event types delivered to the endpoint; ["*"] means all public events and does not include provider.raw_event.

signing_enabled
boolean

true when a signing secret is set and deliveries are signed.

retry_policy
object

Retry settings returned by the API. max_attempts counts retries after the initial delivery, defaults to 3, and is limited to 0-5.

max_attempts
integer

Configured retries after the initial delivery, from 0 to 5.

Responses

201

201 Created

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested provider resource could not be found.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400
Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401
Check X-Api-Key and whether the workspace is active.