API Reference

Webhook Endpoints

Get webhook endpoint

Returns one webhook endpoint configuration.

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

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.

Prepare your parameters
account_id
Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request parameters

Headers

X-Api-Key
stringrequired

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

Path parameters

endpoint_id
stringrequired

Identifier used in the webhook endpoints route.

Query parameters

account_id
string

Optional public account ID, e.g. acc_example. Must not be empty, whitespace-only, or repeated. Use exactly account_id; case variants return 400 invalid_request, not omission. Listing without it returns only workspace endpoints; with it, only independent account configurations (data=[] if none, without inherited workspace configurations). Get, deactivate, and delete only validate existing ownership; a mismatch returns 400 invalid_request. An explicit account outside the workspace or not found returns 404 account_not_found (20020).

minLength: 1 · pattern: \S

Request body

This endpoint does not require a JSON request body.

Understand the result

Read the endpoint’s scope, status, subscriptions, signing_enabled and retry policy. A successful query confirms configuration only; it does not prove event delivery.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "message.received"
    ],
    "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 eligible 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.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested resource was not found. Check error.code and the current operation.

500

Internal Server Error

The service encountered an unexpected error.

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

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
account_not_found · 20020 · 404

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
get_webhook_endpoint_failed · 40002 · 500

Get webhook endpoint: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

Illustrative JSON; message varies with the actual cause · 500 · 40002
{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40002",
    "message": "Failed to get webhook endpoint"
  }
}
get_webhook_endpoint_failed · 40006 · 500

The target webhook endpoint was not found in this scope. GET, PATCH and deactivate keep their operation-specific code and HTTP 500, with numeric_code=40006. This detail does not apply to the idempotent DELETE, which returns 204 for an absent endpoint.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 500 · 40006
{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40006",
    "message": "Webhook endpoint not found"
  }
}