← Все статьи
Гайд

Webhook аккаунта UnifyPort: почему события не приходят в workspace

Если webhook рабочего пространства UnifyPort получает события других аккаунтов мессенджеров, но не одного конкретного, проверьте независимую webhook-конфигурацию этого аккаунта. Настройки аккаунта имеют приоритет над настройками рабочего пространства. Неактивный endpoint или отсутствие нужной подписки не переключают доставку на workspace автоматически. Удаление последнего независимого endpoint восстанавливает наследование для последующих первоначальных доставок, а не для пропущенных событий.

Главное

  • Endpoint рабочего пространства и endpoint аккаунта — разные уровни конфигурации, а не основная и резервная точки доставки.
  • Запросите оба списка: без параметра аккаунта возвращаются только endpoint рабочего пространства.
  • Пустой список аккаунта означает отсутствие независимой конфигурации, а не отсутствие действующего маршрута.
  • Деактивация сохраняет приоритет настроек аккаунта. Для восстановления наследования нужно удалить последний независимый endpoint.
  • Маршрутизацию, подписки, проверку подписи и состояние подключения проверяют отдельно.

Какая конфигурация определяет получателя событий

В справочнике создания webhook endpoint описано необязательное поле тела запроса account_id. Оно связывает новый endpoint с аккаунтом мессенджера. Без него создаётся endpoint рабочего пространства. В ответах независимый endpoint содержит account_id, а у endpoint рабочего пространства это поле отсутствует.

Конфигурация аккаунтаНаследование workspaceЧто проверить
Независимых endpoint нетДействуетСтатус и подписки workspace
Есть active endpoint с подходящей подпискойЗаменено настройками аккаунтаПолучатель и настройки подписи аккаунта
Независимые endpoint есть, но все inactiveАвтоматического переключения нетНужна ли ещё отдельная конфигурация
Active endpoint не подписан на событиеАвтоматического переключения нетПодписки endpoint аккаунта
Последний независимый endpoint удалёнВосстановлено для последующих первоначальных доставокГотовность workspace и новое тестовое событие

Представим, что сборщик workspace подписан на message.received, а endpoint одного аккаунта — только на account.status.updated. Это условная конфигурация, не описание реального инцидента. Подписка workspace не компенсирует событие, исключённое фильтром аккаунта. Нужно исправить настройки аккаунта либо осознанно восстановить наследование.

Руководство по фильтрам событий объясняет выбор имён подписок. Здесь сначала нужно ответить на другой вопрос: какой уровень конфигурации отвечает за доставку этого аккаунта?

Два запроса только на чтение

Для обоих запросов используйте один серверный X-Api-Key: именно ключ определяет рабочее пространство. Ниже показаны пути запросов. Замените acc_example реальным публичным ID из результата чтения аккаунта:

GET /v1/webhook-endpoints
GET /v1/webhook-endpoints?account_id=acc_example

Согласно справочнику списка webhook endpoint, первый запрос возвращает только конфигурации workspace, второй — только независимые конфигурации указанного аккаунта. Унаследованные endpoint рабочего пространства во второй список не включаются. Поэтому успешный ответ data: [] означает «независимых endpoint нет», а не «маршрута Webhook нет».

Зафиксируйте ID endpoint, привязку аккаунта, URL, status, subscribed_events, signing_enabled и политику повторных попыток. Не пропускайте inactive-записи: они также влияют на наследование. Не включайте секреты и содержимое сообщений в диагностическую запись.

Имя параметра должно быть точно account_id. Пустое значение, пробелы, повторяющиеся параметры и другой регистр не равнозначны отсутствию параметра. Если явно указанный аккаунт не найден или находится вне рабочего пространства, возвращается 404 account_not_found. Исправьте ID и workspace; не считайте ошибку пустым списком.

Если оба уровня настроены правильно, отдельно проверьте авторизацию и runtime, затем проследите поддерживаемое новое событие до проверки получателем и долговременного сохранения. Не перезапускайте исправный аккаунт только потому, что проверяете не тот URL.

Исправить отдельный маршрут или восстановить наследование

Сохранить получателя для конкретного аккаунта

Используйте обновление webhook endpoint, чтобы исправить URL, активность или подписки существующего endpoint. Сохраните проверенные настройки подписи и повторных попыток. Пустой signing_secret отключает подпись; не переносите неподписанный пример в production.

Если у аккаунта уже есть active независимый endpoint, создание ещё одного active endpoint может вернуть 409 account_webhook_already_exists с числовым кодом 40008. То же ограничение действует при переходе другого endpoint из inactive в active. Обновлять уже активный endpoint с сохранением active разрешено, в том числе в старых конфигурациях с несколькими активными endpoint. Не рассчитывайте на автоматическое удаление таких старых записей. Это ограничение не распространяется на endpoint рабочего пространства.

Привязку аккаунта изменить нельзя. При обновлении account_id только проверяет исходную принадлежность; отсутствие поля сохраняет её. Ни отсутствие поля, ни null не превращают endpoint аккаунта в endpoint workspace. Существующий endpoint рабочего пространства также нельзя переназначить аккаунту.

Вернуть аккаунт к получателю workspace

Сначала убедитесь, что получатель рабочего пространства активен, подписан на необходимые события и готов проверять подпись и надёжно сохранять данные. Согласуйте последствия с владельцем отдельного рабочего процесса аккаунта.

Затем явно удалите независимую конфигурацию через Delete webhook endpoint. Проверьте все записи: оставшийся inactive endpoint всё ещё сохраняет конфигурацию аккаунта. Повторно запросите список с account_id и убедитесь, что независимых endpoint больше нет. Успешное удаление возвращает 204 без тела ответа.

Это изменение маршрута, а не универсальный способ обслуживания. Если нужно временно остановить только CRM или AI-обработку, сравнение вариантов обслуживания Webhook объясняет, почему остановка downstream-воркеров может быть лучше изменения endpoint.

Проверить новый маршрут, не обещая восстановление истории

После изменения конфигурации отправьте контролируемое новое тестовое сообщение. На ожидаемом получателе проверьте аккаунт и событие, подтвердите подпись по контракту доставки, надёжно сохраните данные и только затем подтвердите получение. Результат дальнейшей обработки проверяется отдельно.

Это рекомендуемые приёмочные проверки, а не тесты, уже выполненные в вашем workspace. Если запрос изменения конфигурации завершился тайм-аутом, прочитайте текущее состояние перед повторной записью. Правило наследования относится к последующим первоначальным доставкам и не определяет поведение каждой попытки, уже находящейся в обработке.

Неофициальный интерфейс UnifyPort предоставляет унифицированный поток событий, но не гарантирует повторную доставку пропущенных payload. Успешный новый тест подтверждает работу нового маршрута, а не восстановление данных за предыдущий период.

Частые вопросы

Деактивация endpoint аккаунта возвращает доставку в workspace?

Нет. Независимая inactive-конфигурация сохраняет приоритет. Наследование восстанавливается после удаления последнего независимого endpoint и касается последующих первоначальных доставок.

Поможет wildcard в подписках рабочего пространства?

Он не исправляет приоритет настроек аккаунта. Измените действующую конфигурацию аккаунта либо осознанно удалите её для восстановления наследования.

Почему список endpoint аккаунта пуст?

Успешный пустой результат означает отсутствие независимых endpoint. Прочитайте список workspace, чтобы проверить унаследованную конфигурацию. Ответ с ошибкой не является пустым результатом.

Следующий шаг и источники

Начните со списка webhook endpoint и сравните оба уровня до любых изменений.

Официальные материалы продукта проверены 2026-11-15:

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.