Справочник API

Webhook-эндпоинты

Создать Webhook-эндпоинт

Создаёт Webhook на абсолютном HTTP(S) URL; для production рекомендуется HTTPS. status: active или inactive. subscribed_events принимает публичные события или ["*"]; max_attempts: 0..5. Создание active-эндпоинта аккаунта при наличии другого active-эндпоинта того же аккаунта возвращает 409 account_webhook_already_exists (40008). Доступ к событиям звонков определяется is_beta рабочего пространства. При доступе к тестированию *, пустой или отсутствующий subscribed_events включают события звонков; конкретный список включает только перечисленные события. Без доступа можно использовать wildcard, но события звонков не доставляются; их явная подписка возвращает 403 beta_feature_not_enabled. Право проверяется при каждой доставке, повторе и повторной обработке dead letter; ошибка проверки не даёт доступ. Обычные записи звонков message.* независимы.

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

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

all

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

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

При создании или повторном включении endpoint аккаунта для одного account_id допускается только один active; конфликт возвращает 409 account_webhook_already_exists (40008). Endpoint аккаунта в состоянии inactive и endpoint рабочего пространства могут быть множественными. Обновление уже active endpoint с сохранением active разрешено, в том числе для старых конфигураций с несколькими active.

Откуда взять параметры
account_id
Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт

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

Заголовки

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

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

Content-Type
stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Тело запроса

account_id
string

Необязательный публичный ID аккаунта в body, например acc_example. При создании привязывает эндпоинт к аккаунту; при пропуске создаётся эндпоинт рабочего пространства. При обновлении лишь проверяет исходную привязку; пропуск сохраняет принадлежность. Нельзя сменить аккаунт, преобразовать эндпоинт рабочего пространства в эндпоинт аккаунта или очистить привязку. Не допускаются query, null, пустые строки, строки только из пробельных символов и повторные поля. Имя поля должно быть строго account_id; варианты с другим регистром в body или query и несовпадение принадлежности возвращают 400 invalid_request. Если указанный аккаунт не найден или не принадлежит текущему рабочему пространству, возвращается 404 account_not_found (20020). Независимая конфигурация аккаунта имеет приоритет над конфигурацией рабочего пространства. Отключение или отсутствие подписки на событие не вызывает перехода к конфигурации рабочего пространства. После удаления последнего независимого эндпоинта последующие первоначальные доставки снова наследуют её. Проверка конфликта активации касается только других active-эндпоинтов с тем же account_id; эндпоинты рабочего пространства не ограничены. Условия описаны в status.

minLength: 1 · pattern: \S

url
stringобязательно

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

format: uri

status
stringобязательно

Статус эндпоинта: active или inactive. Создание active-эндпоинта аккаунта или переход inactive→active при наличии другого active-эндпоинта того же аккаунта возвращает 409 account_webhook_already_exists (40008). Допускается несколько inactive-эндпоинтов аккаунта и несколько эндпоинтов рабочего пространства. Существующий active-эндпоинт можно обновлять, сохраняя active, даже при наличии нескольких исторических active-эндпоинтов; автоматическая очистка не выполняется.

enum: active, inactive

subscribed_events[]
string[]

Подписка на публичные стандартные события. Отсутствие поля, пустой массив или наличие * означает все публичные события, включая добавленное contact.updated, но не provider.raw_event. Для получения только выбранных событий явно перечислите их имена.

signing_secret
string

Опциональный секрет подписи Webhook. В примерах используйте плейсхолдеры.

retry_policy
object

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

max_attempts
integer

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

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

Проверьте возвращённую конфигурацию. Для проверки доставки endpoint должен быть active и подписан на нужное событие. Проверяйте подпись только при signing_enabled=true; сначала сохраните событие, затем подтвердите его ответом 2xx.

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

Тело ответа

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.

Ответы

201

201 Created

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

Запрос распознан, но операция запрещена.

404

Not Found

Запрошенный ресурс не найден. Сверьте error.code с текущей операцией.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

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

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

invalid_request · 10000 · 400
Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
missing_api_key · 11000 · 401
Проверьте X-Api-Key и активность рабочего пространства.
invalid_api_key · 11001 · 401
Проверьте X-Api-Key и активность рабочего пространства.
account_webhook_already_exists · 40008 · 409
Запросите отдельные endpoint аккаунта с account_id и обновите существующий active. Для переключения сначала отключите прежний active, затем включите другой. Не повторяйте создание или повторное включение автоматически.