Webhook-эндпоинты
Получить Webhook-эндпоинт
Возвращает конфигурацию одного Webhook-эндпоинта.
https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}Поддерживаемые каналы
Перед вызовом
Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.
Откуда взять параметры
- account_id
- Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт
Параметры запроса
Заголовки
X-Api-KeyAPI-ключ рабочей области. Рабочая область определяется по этому заголовку.
Параметры пути
endpoint_idИдентификатор для маршрута раздела webhook endpoints.
Параметры запроса
account_idНеобязательный публичный ID аккаунта, например acc_example. Пустое значение, строка только из пробельных символов и повторное указание запрещены. Имя параметра должно быть строго account_id; варианты с другим регистром возвращают 400 invalid_request, а не считаются пропуском. При получении списка без параметра возвращаются только эндпоинты рабочего пространства, с параметром — только независимые настройки аккаунта (data=[], если их нет, без унаследованных настроек рабочего пространства). Получение, деактивация и удаление лишь проверяют текущую принадлежность аккаунту; несовпадение возвращает 400 invalid_request. Если указанный аккаунт не найден или не принадлежит текущему рабочему пространству, возвращается 404 account_not_found (20020).
minLength: 1 · pattern: \S
Тело запроса
Этот эндпоинт не требует JSON-тела запроса.
Как понять результат
Проверьте принадлежность endpoint, status, подписки, signing_enabled и настройки повторов. Успешное чтение подтверждает конфигурацию, но не доставку событий.
Ответ 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Идентификатор 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 с текущей операцией.
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" } }- 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" } }- get_webhook_endpoint_failed · 40002 · 500
Получить Webhook-эндпоинт: сервис не смог получить достоверный результат запроса.
Действия и повторы: Сохраните request_id, проверьте идентификаторы и доступ аккаунта. Повторяйте чтение после проверки причины; неудачный запрос не доказывает отсутствие ресурса или пустой результат.
Пример JSON; message зависит от фактической причины · 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
Webhook-эндпоинт не найден в этой области. GET, PATCH и деактивация сохраняют код своей операции и HTTP 500 с numeric_code=40006. Это уточнение не относится к идемпотентному DELETE: при отсутствии эндпоинта он возвращает 204.
Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.
Пример JSON; message зависит от фактической причины · 500 · 40006
{ "request_id": "req_example", "error": { "code": "get_webhook_endpoint_failed", "numeric_code": "40006", "message": "Webhook endpoint not found" } }