Webhook-эндпоинты

Обновить Webhook-эндпоинт

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

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

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

all

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

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

PATCH заменяет конфигурацию Webhook. Передайте все сохраняемые настройки: без signing_secret подпись отключается; без subscribed_events снова выбираются все публичные события; без retry_policy/max_attempts восстанавливаются три повторные попытки. Сначала прочитайте текущую конфигурацию и укажите сохранённый секрет подписи.

Запрос

curl -X PATCH "https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook-updated",
  "status": "inactive",
  "subscribed_events": ["message.delivered", "message.read"],
  "signing_secret": "",
  "retry_policy": {
    "max_attempts": 1
  }
}'

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

Заголовки

X-Api-Key

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

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

Content-Type

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

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

Параметры пути

endpoint_id

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

Идентификатор для маршрута раздела webhook endpoints.

Тело запроса

account_id

string

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

minLength: 1 · pattern: \S

url

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

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

format: uri

status

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

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

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.

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

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

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

Тело ответа

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 отсутствует или недействителен.

403

Forbidden

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

404

Not Found

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

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

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

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