Справочник API

Webhook-эндпоинты

Список Webhook-эндпоинтов

Возвращает Webhook-эндпоинты текущего workspace, включая подписки на события, состояние подписи, статус и retry-политику.

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

Поддерживаемые каналы

all

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Параметры запроса

Заголовки

X-Api-Key
stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Параметры запроса

account_id
string

Необязательный публичный ID аккаунта, например acc_example. Пустое значение, строка только из пробельных символов и повторное указание запрещены. Имя параметра должно быть строго account_id; варианты с другим регистром возвращают 400 invalid_request, а не считаются пропуском. При получении списка без параметра возвращаются только эндпоинты рабочего пространства, с параметром — только независимые настройки аккаунта (data=[], если их нет, без унаследованных настроек рабочего пространства). Получение, деактивация и удаление лишь проверяют текущую принадлежность аккаунту; несовпадение возвращает 400 invalid_request. Если указанный аккаунт не найден или не принадлежит текущему рабочему пространству, возвращается 404 account_not_found (20020).

minLength: 1 · pattern: \S

Тело запроса

Этот эндпоинт не требует JSON-тела запроса.

Как понять результат

Успех настройки не доказывает доставку. Вызовите нужное событие и проверьте получение, подпись и подтверждение на приёмнике.

Ответ 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
      }
    }
  ]
}

Тело ответа

id
string

Идентификатор Webhook-эндпоинта (we_...).

account_id
string

Публичный ID аккаунта для независимого эндпоинта аккаунта; у эндпоинтов рабочего пространства поле отсутствует, null не возвращается.

minLength: 1

url
string

Абсолютный HTTP(S) URL доставки webhook; для production рекомендуется HTTPS.

format: uri

status
string

Статус эндпоинта: active или inactive.

enum: active, inactive

subscribed_events[]
string[]

Публичные стандартные события эндпоинта; ["*"] означает все публичные события без provider.raw_event.

signing_enabled
boolean

true, когда задан секрет подписи и доставки подписываются.

retry_policy
object

max_attempts считает повторы после первой доставки; по умолчанию 3, диапазон 0–5.

max_attempts
integer

Настроенное число повторов после первой доставки, от 0 до 5.

Ответы

200

200 OK

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

404

Not Found

Запрошенный ресурс провайдера не найден.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

При ошибке запроса

Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок

invalid_request · 10000 · 400
Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
invalid_api_key · 11001 · 401
Проверьте X-Api-Key и активность рабочего пространства.