Webhook-эндпоинты
Обновить Webhook-эндпоинт
Обновляет Webhook. url — абсолютный HTTP(S), для production рекомендуется HTTPS; status: active или inactive. Пустой signing_secret отключает подпись, max_attempts: 0..5. Переход inactive→active для эндпоинта аккаунта при наличии другого active-эндпоинта того же аккаунта возвращает 409 account_webhook_already_exists (40008). Обновления active→active разрешены. Обычные рабочие пространства получают исходящие call.answered и call.ended, если они явно указаны в subscribed_events. Участники бета-тестирования могут также использовать *, пустой список или пропустить список. При доставке, повторе и повторной обработке проверяются текущий доступ и подписка. Записи message.* обрабатываются отдельно.
https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}Поддерживаемые каналы
Перед вызовом
Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.
PATCH заменяет конфигурацию Webhook. Передайте все сохраняемые настройки: без signing_secret подпись отключается; без subscribed_events снова выбираются все публичные события; без retry_policy/max_attempts восстанавливаются три повторные попытки. Сначала прочитайте текущую конфигурацию и укажите сохранённый секрет подписи.
При создании или повторном включении 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-KeyAPI-ключ рабочей области. Рабочая область определяется по этому заголовку.
Content-TypeИспользуйте application/json при отправке JSON-тела запроса.
Параметры пути
endpoint_idИдентификатор для маршрута раздела webhook endpoints.
Тело запроса
account_idНеобязательный публичный 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Абсолютный HTTP(S) URL получателя Webhook; для production рекомендуется HTTPS.
format: uri
statusСтатус эндпоинта: active или inactive. Создание active-эндпоинта аккаунта или переход inactive→active при наличии другого active-эндпоинта того же аккаунта возвращает 409 account_webhook_already_exists (40008). Допускается несколько inactive-эндпоинтов аккаунта и несколько эндпоинтов рабочего пространства. Существующий active-эндпоинт можно обновлять, сохраняя active, даже при наличии нескольких исторических active-эндпоинтов; автоматическая очистка не выполняется.
enum: active, inactive
subscribed_events[]Подписка на публичные стандартные события. Отсутствие поля, пустой массив или наличие * означает публичные события, доступные рабочему пространству, включая добавленное contact.updated, но не provider.raw_event. Для получения только выбранных событий явно перечислите их имена. Подписка на message.read также получает квитанции воспроизведения WhatsApp со значением played в data.event.receipt_type. Обычные рабочие пространства получают исходящие call.answered и call.ended, если они явно указаны в subscribed_events. Участники бета-тестирования могут также использовать *, пустой список или пропустить список. При доставке, повторе и повторной обработке проверяются текущий доступ и подписка. Записи message.* обрабатываются отдельно.
signing_secretОпциональный секрет подписи Webhook. В примерах используйте плейсхолдеры.
retry_policyobjectmax_attempts — число повторов после первой доставки: по умолчанию 3, диапазон 0–5; 0 означает только первую доставку.
retry_policymax_attempts — число повторов после первой доставки: по умолчанию 3, диапазон 0–5; 0 означает только первую доставку.
max_attemptsЧисло повторов после первой доставки, от 0 до 5.
Как понять результат
Проверьте возвращённую конфигурацию. Для проверки доставки endpoint должен быть active и подписан на нужное событие. Проверяйте подпись только при signing_enabled=true; сначала сохраните событие, затем подтвердите его ответом 2xx.
Ответ 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Идентификатор Webhook-эндпоинта (we_...).
account_idПубличный ID аккаунта для независимого эндпоинта аккаунта; у эндпоинтов рабочего пространства поле отсутствует, null не возвращается.
minLength: 1
urlАбсолютный HTTP(S) URL доставки webhook; для production рекомендуется HTTPS.
format: uri
statusСтатус эндпоинта: active или inactive.
enum: active, inactive
subscribed_events[]Публичные стандартные события эндпоинта; ["*"] означает публичные события, доступные рабочему пространству без provider.raw_event.
signing_enabledtrue, когда задан секрет подписи и доставки подписываются.
retry_policyobjectmax_attempts считает повторы после первой доставки; по умолчанию 3, диапазон 0–5.
retry_policymax_attempts считает повторы после первой доставки; по умолчанию 3, диапазон 0–5.
max_attemptsНастроенное число повторов после первой доставки, от 0 до 5.
Ответы
200200 OK
Запрос выполнен. См. пример тела ответа.
400Bad Request
Тело запроса, путь или параметры некорректны.
401Unauthorized
Заголовок X-Api-Key отсутствует или недействителен.
403Forbidden
Запрос распознан, но операция запрещена.
404Not Found
Запрошенный ресурс не найден. Сверьте error.code с текущей операцией.
409Conflict
Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.
500Internal Server Error
Сервис столкнулся с неожиданной ошибкой.
При ошибке запроса
Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок
Сопоставляйте HTTP-статус, error.code и error.numeric_code с текущей операцией. Числовой код — строка. Сохраняйте request_id для диагностики: это не ключ идемпотентности и не идентификатор задачи.
- invalid_request · 10000 · 400
Проверьте JSON и обязательные поля.
Действия и повторы: Исправьте параметры с учётом операции и канала. Повтор неизменённого неверного запроса не устранит ошибку.
Пример JSON; message зависит от фактической причины · 400 · 10000
{ "request_id": "req_example", "error": { "code": "invalid_request", "numeric_code": "10000", "message": "Invalid request parameters" } }- invalid_target_workspace · 11003 · 400
Целевое рабочее пространство в заголовке переопределения пусто или задано неверно. Удалите этот заголовок и используйте API-ключ нужного пространства.
Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.
Действия и повторы: Исправьте параметры с учётом операции и канала. Повтор неизменённого неверного запроса не устранит ошибку.
Пример JSON; message зависит от фактической причины · 400 · 11003
{ "request_id": "req_example", "error": { "code": "invalid_target_workspace", "numeric_code": "11003", "message": "Invalid target workspace" } }- invalid_api_key · 11001 · 401
Проверьте правильность и активность ключа API.
Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.
Пример JSON; message зависит от фактической причины · 401 · 11001
{ "request_id": "req_example", "error": { "code": "invalid_api_key", "numeric_code": "11001", "message": "Invalid API key" } }- missing_api_key · 11000 · 401
Добавьте заголовок X-Api-Key.
Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.
Пример · 401 · 11000
{ "request_id": "req_xxx", "error": { "code": "missing_api_key", "numeric_code": "11000", "message": "Missing X-Api-Key header" } }- beta_feature_not_enabled · 41002 · 403
Явная подписка на зарезервированное событие call.incoming требует доступа рабочего пространства к закрытому тестированию.
Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.
Пример · 403 · 41002
{ "request_id": "req_example", "error": { "code": "beta_feature_not_enabled", "numeric_code": "41002", "message": "Beta feature not enabled" } }- workspace_override_forbidden · 11002 · 403
Запрос пытается переопределить рабочее пространство без необходимых прав. Удалите заголовок переопределения и используйте API-ключ нужного рабочего пространства.
Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.
Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.
Пример JSON; message зависит от фактической причины · 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
Проверьте account_id и используйте X-Api-Key рабочего пространства владельца аккаунта. Текущий ключ не даёт доступа к аккаунту, которого нет в этом пространстве.
Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.
Пример JSON; message зависит от фактической причины · 404 · 20020
{ "request_id": "req_example", "error": { "code": "account_not_found", "numeric_code": "20020", "message": "Account not found" } }- target_workspace_not_found · 11004 · 404
Переопределённое рабочее пространство не найдено или недоступно. Проверьте его принадлежность, удалите заголовок переопределения и используйте нужный API-ключ; повторы не дадут доступ.
Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.
Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.
Пример JSON; message зависит от фактической причины · 404 · 11004
{ "request_id": "req_example", "error": { "code": "target_workspace_not_found", "numeric_code": "11004", "message": "Target workspace not found" } }- account_webhook_already_exists · 40008 · 409
Запросите отдельные endpoint аккаунта с account_id и обновите существующий active. Для переключения сначала отключите прежний active, затем включите другой. Не повторяйте создание или повторное включение автоматически.
Действия и повторы: Перед повторной отправкой прочитайте настройки эндпоинта и его привязку к аккаунту. PATCH заменяет настройки: сохраните нужные подписки, подпись и политику повторов. При конфликте active обновите существующий эндпоинт либо деактивируйте его перед включением другого.
Пример · 409 · 40008
{ "request_id": "req_example_webhook_conflict", "error": { "code": "account_webhook_already_exists", "numeric_code": "40008", "message": "Account already has an active webhook endpoint" } }- update_webhook_endpoint_failed · 40003 · 500
Обновить Webhook-эндпоинт: изменение прервано неклассифицированной ошибкой; итоговое состояние нужно проверить.
Действия и повторы: Перед повторной отправкой прочитайте настройки эндпоинта и его привязку к аккаунту. PATCH заменяет настройки: сохраните нужные подписки, подпись и политику повторов. При конфликте active обновите существующий эндпоинт либо деактивируйте его перед включением другого.
Пример JSON; message зависит от фактической причины · 500 · 40003
{ "request_id": "req_example", "error": { "code": "update_webhook_endpoint_failed", "numeric_code": "40003", "message": "Failed to update webhook endpoint" } }- update_webhook_endpoint_failed · 40006 · 500
Webhook-эндпоинт не найден в этой области. GET, PATCH и деактивация сохраняют код своей операции и HTTP 500 с numeric_code=40006. Это уточнение не относится к идемпотентному DELETE: при отсутствии эндпоинта он возвращает 204.
Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.
Пример JSON; message зависит от фактической причины · 500 · 40006
{ "request_id": "req_example", "error": { "code": "update_webhook_endpoint_failed", "numeric_code": "40006", "message": "Webhook endpoint not found" } }