API Reference

Webhook Endpoints

Update webhook endpoint

Updates a webhook endpoint. url must be an absolute HTTP(S) URL and HTTPS is recommended for production; status must be active or inactive. subscribed_events accepts known public standard events or ["*"]; an empty signing_secret disables signing, and retry_policy.max_attempts accepts 0..5.

PATCHhttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

Before you call

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

PATCH replaces the webhook configuration. Send every setting you want to retain: omitting signing_secret disables signing, omitting subscribed_events restores all public events, and omitting retry_policy/max_attempts restores three retries. Read the existing configuration first and supply your saved signing secret.

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.

Path parameters

endpoint_id
stringrequired

Identifier used in the webhook endpoints route.

Request body

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 types delivered to the endpoint. Use ["*"] for every public standard event; provider.raw_event is not included.

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 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook-updated",
    "status": "inactive",
    "subscribed_events": [
      "message.delivered",
      "message.read"
    ],
    "signing_enabled": false,
    "retry_policy": {
      "max_attempts": 1
    }
  }
}

Response body

id
string

Webhook endpoint identifier (we_...).

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

200

200 OK

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.

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.