Руководство August 19, 2026

Фильтры событий UnifyPort Webhook: subscribed_events или wildcard?

Для производственного обработчика с одной задачей указывайте нужные события в subscribed_events. Используйте ["*"], если эндпоинт служит полным сборщиком событий или команда ещё определяет требования процесса. Wildcard включает все публичные стандартные события, но не внутренние raw-события. Для входящего ящика начните с message.received и добавляйте события жизненного цикла аккаунта, только если тот же сервис отвечает за состояние подключения.

Главное

subscribed_events принимает точные имена публичных событий либо только ["*"] для всего публичного каталога.
Неизвестные имена отклоняются при создании или обновлении эндпоинта.
Подписка не означает, что каждый провайдер формирует это событие: проверяйте матрицу поддержки.
message.received может описывать входящий или исходящий трафик, поэтому проверяйте data.message.direction.
Фильтрация, HMAC-подпись, подтверждение доставки и повторные попытки настраиваются отдельно.

Что контролирует `subscribed_events`

UnifyPort отправляет выбранные в subscribed_events события на webhook-эндпоинт методом HTTP POST. Стандартная оболочка всегда содержит id, type, provider, account_id, occurred_at и зависящий от события объект data. Допустимые имена и форматы payload перечислены в каталоге стандартных событий.

Минимальная подписка для входящих сообщений:

{
  "subscribed_events": ["message.received"]
}

Но обработчик всё равно должен проверить направление:

if (
  event.type === 'message.received' &&
  event.data?.message?.direction === 'inbound'
) {
  await storeInboundMessage(event);
}

Событие означает, что на подключённом messaging account замечено сообщение. Оно не обещает только входящий трафик.

Wildcard задаётся так:

{
  "subscribed_events": ["*"]
}

Используйте его как полный вариант и не смешивайте "*" с именованными событиями в одном массиве. Он включает все публичные стандартные события, но не открывает внутренние raw-события.

Три практических набора фильтров

1. Только входящий ящик

Подходит сервису, который сохраняет и маршрутизирует обращения клиентов:

{
  "subscribed_events": ["message.received"]
}

Обрабатывайте только записи, где data.message.direction равно inbound. Если позже понадобятся изменения, удаления, реакции или статусы доставки, добавьте точные имена событий после того, как определите правила обновления сохранённого состояния.

2. Входящий ящик и состояние аккаунта

Этот набор нужен, если тот же сервис должен показывать истёкшую авторизацию или отключённый runtime:

{
  "subscribed_events": [
    "message.received",
    "account.status.updated",
    "account.started",
    "account.auth.required",
    "account.auth.succeeded",
    "account.auth.failed"
  ]
}

Не воспринимайте каждое событие состояния как команду перезапуска. Сохраните auth_status и runtime_status, затем заново проверьте аккаунт перед действием. Инструкция по восстановлению runtime messaging account объясняет, когда нужны refresh, reconnect, start или повторная авторизация.

3. Полный сборщик событий

Выберите ["*"], если эндпоинт является общей границей приёма, а распределение выполняется ниже по потоку. WhatsApp, Telegram, LINE, TikTok, Zalo и X могут поступать в одну подписанную очередь, а отдельные потребители будут разбирать сообщения, статусы доставки, группы и состояние аккаунтов.

Даже при wildcard нужен обработчик по умолчанию для будущих публичных типов. Безопасно сохраните оболочку, подтвердите доставку, а неизвестный тип направьте в наблюдаемую изолированную очередь. Нельзя считать каждое событие сообщением.

Создание эндпоинта с явным фильтром

Реальный маршрут API — POST /v1/webhook-endpoints. Следующий запрос создаёт активный подписанный эндпоинт для сообщений и состояния аккаунта:

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"https://inbox.example.com/webhooks/unifyport\",
    \"status\": \"active\",
    \"subscribed_events\": [
      \"message.received\",
      \"account.status.updated\",
      \"account.auth.required\"
    ],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\",
    \"retry_policy\": { \"max_attempts\": 3 }
  }"

Поля запроса описаны в справочнике создания webhook-эндпоинта. retry_policy.max_attempts — это число повторов после первой доставки. Документированное значение по умолчанию 3 означает первый запрос и до трёх повторов. Допустимый диапазон — от 0 до 5.

Чтобы позднее изменить фильтр, используйте документированный маршрут PATCH /v1/webhook-endpoints/{endpoint_id} и отправьте новый subscribed_events. Для создания и обновления действуют одинаковые правила проверки имён.

Отделяйте фильтрацию от безопасности доставки

Фильтр решает, что отправляет UnifyPort. signing_secret определяет наличие заголовков X-Device-Timestamp и X-Device-Signature. Если подпись включена, до разбора JSON проверьте шестнадцатеричный HMAC-SHA256 от строки из timestamp, точки и исходных байтов тела запроса.

Любой ответ 2xx подтверждает доставку. Ошибки соединения и HTTP 408, 429, 5xx повторяются согласно настройке; остальные ответы 4xx не повторяются. Доставка работает по принципу at-least-once, поэтому повторы обычных событий должны обрабатываться идемпотентно.

Полная реализация получателя приведена в руководстве по доставке webhook и проверке подписи, а детали — в инструкции по HMAC-защите от повторной отправки и идемпотентности.

Проверяйте поддержку провайдера до добавления события

Публичный каталог задаёт корректные имена, но парсеры провайдеров отображают не все события. message.received и основные события аккаунта имеют широкую поддержку; статусы доставки, изменения сообщений, обновления диалогов и групп зависят от провайдера.

До того как потребитель начнёт зависеть от события, проверьте различия webhook-событий по провайдерам. Корректная подписка является фильтром, а не гарантией того, что исходный аккаунт сформирует событие.

Если вы строите автоматизацию, а не универсальный сборщик, изучите пример подписанного webhook для n8n и WhatsApp. Он показывает, почему проверка и надёжный приём должны находиться перед AI-процессом.

Ограничения и компромиссы

Явный список уменьшает шум и чётко задаёт ответственность сервиса, но требует обновления конфигурации при появлении новой задачи. Wildcard помогает не пропустить новый публичный тип, однако потребители должны принимать больше событий и быть готовы к расширению каталога.

У UnifyPort нет общего REST API для чтения истории сообщений и гарантированного воспроизведения пропущенных payload. Зарегистрируйте получатель до подключения производственных messaging account и сохраняйте нужные события при поступлении. Ограниченная синхронизация истории WhatsApp помогает поддерживать непрерывность, но не заменяет ваше хранилище событий.

UnifyPort предоставляет неофициальный интерфейс. Если проекту нужен официальный путь сертификации или специфическая возможность провайдера вне документированной матрицы, используйте официальный API соответствующей платформы.

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

Что выбрать: `message.received` или `["*"]`?

Для специализированного входящего ящика используйте message.received. Для общего сборщика всех публичных стандартных событий — ["*"].

`message.received` содержит только входящие сообщения?

Нет. Если процесс работает только с входящими, проверяйте, что data.message.direction равно inbound.

Можно ли подписаться на внутренние события провайдера?

Нет. subscribed_events принимает только публичные стандартные имена, а wildcard не раскрывает внутренние raw-события.

Что произойдёт при ошибке в имени события?

Запрос создания или обновления отклонит неизвестное имя, а не сохранит фильтр, который никогда не сработает.

Гарантирует ли `["*"]` все события от каждого провайдера?

Нет. Он выбирает все публичные стандартные типы, но фактическая поддержка и доступность у источника зависят от провайдера.

Следующий шаг

Откройте справочник Create webhook endpoint, выберите один из трёх наборов и зарегистрируйте получатель до подключения производственных messaging account.

Источники

Проверено 19 августа 2026 года: