Справочник API

Webhook-эндпоинты

Деактивировать Webhook-эндпоинт

Переводит Webhook-эндпоинт в статус inactive, не удаляя его.

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

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

all

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

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

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

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

Заголовки

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

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

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

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

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

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

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-тела запроса.

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

Убедитесь, что ответ содержит status=inactive. Новых доставок через этот endpoint не ожидается; отключение не гарантирует отмену уже отправляемых запросов.

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

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

500

Internal 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"
  }
}
deactivate_webhook_endpoint_failed · 40004 · 500

Деактивировать Webhook-эндпоинт: остановка или деактивация не подтверждена; при восстановлении учитывайте намерение остановить ресурс.

Действия и повторы: Проверьте, вступила ли в силу остановка или деактивация. Не запускайте и не переподключайте ресурс, который хотели остановить.

Пример JSON; message зависит от фактической причины · 500 · 40004
{
  "request_id": "req_example",
  "error": {
    "code": "deactivate_webhook_endpoint_failed",
    "numeric_code": "40004",
    "message": "Failed to deactivate webhook endpoint"
  }
}
deactivate_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": "deactivate_webhook_endpoint_failed",
    "numeric_code": "40006",
    "message": "Webhook endpoint not found"
  }
}