Документация Каналы уведомлений

Каналы уведомлений

Mockarty поддерживает отправку уведомлений через внешние мессенджеры — Telegram, Slack, Discord, Microsoft Teams и другие. Пользователи получают оповещения о результатах тестов, находках фаззинга, завершении задач агента и системных событиях прямо в привычный мессенджер.

Архитектура

Система уведомлений использует двухуровневую модель:

  1. Администратор настраивает системные каналы (напр. “Корпоративный Slack”, “Telegram бот”)
  2. Пользователи подключаются к доступным каналам и настраивают, какие события хотят получать

Кроме того, AI-агент может использовать системные каналы для отправки уведомлений без необходимости указывать credentials.

АДМИНИСТРАТОР Настройка каналов Добавить Тест / Удалить настраивает СИСТЕМНЫЕ КАНАЛЫ Telegram Slack Discord Teams + PagerDuty, OpsGenie, Webex... ПОЛЬЗОВАТЕЛЬ Настройки → Мои каналы Подключить Предпочтения привязка ШИНА СОБЫТИЙ test.run.completed | fuzzing.finding.new | agent.task.completed | system.incident.triggered ДИСПЕТЧЕР КАНАЛОВ событие → привязки пользователя → отправка проверка предпочтений Telegram Slack Discord Teams PagerDuty Webhook ... AI Агент send_via_channel прямая отправка

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

Канал Тип Как работает
Telegram Bot API Админ создаёт бота через @BotFather, пользователи подключаются через deeplink
Slack Bot Token / Webhook DM через bot token + поиск по email, или webhook в канал
Discord Webhook Webhook уровня канала, привязка к пользователю не нужна
Microsoft Teams Workflow Webhook Adaptive Card через Power Automate Workflow
Mattermost Webhook Slack-совместимый входящий вебхук
PagerDuty Events API v2 Создаёт инциденты для критичных алертов
OpsGenie Alert API Создаёт алерты с маппингом приоритетов
Google Chat Webhook Webhook уровня пространства
Webex Bot API DM через bot token + email
Generic Webhook HTTP POST Любой URL с опциональной HMAC подписью

Настройка администратором

Добавление канала

  1. Откройте Админ-панель → Каналы уведомлений
  2. Нажмите Добавить канал
  3. Выберите тип канала
  4. Заполните конфигурацию (следуйте подсказкам для каждого типа)
  5. (Опционально) Укажите Namespace — оставьте пустым, чтобы сделать канал глобальным (виден в каждом namespace), либо введите конкретное имя namespace, чтобы ограничить область видимости. Это поле можно безопасно изменить позднее через обновление.
  6. Нажмите Сохранить
  7. Используйте кнопку Тест для проверки подключения

Обновление канала (без раскрытия секретов)

При редактировании существующего канала не нужно повторно вводить токены, webhook URL или другие чувствительные поля — UI отправляет пустую строку для полей, которые вы оставили незаполненными, а сервер сохраняет ранее записанное значение для них. Перезаписываются только те поля, которые вы действительно заполнили. Это позволяет переименовать канал, переключить его enabled, или перенести между namespace без повторного раскрытия секретов.

Журнал аудита администратора

Каждое изменение канала, инициированное администратором, записывается в журнал аудита (просмотр в Админ-панель → Журнал аудита). Три кода действий идентифицируют события:

Действие Когда срабатывает Захватываемые поля
create_notification_channel Новый канал сохранён type, name, enabled, актор, IP, namespace
update_notification_channel Успешный PUT канала type, name, enabled, актор, IP, namespace
delete_notification_channel Успешный DELETE канала type, name (снимок перед удалением), актор, IP, namespace

Секретные поля (токены ботов, webhook URL, пароли) никогда не попадают в журнал аудита — записываются только публичные метаданные. Используйте этот журнал, чтобы отследить, кто настроил канал, когда он был отключён или какой администратор удалил получателя, переставшего получать алерты.

Примеры настройки

Telegram

  1. Откройте Telegram, найдите @BotFather
  2. Отправьте /newbot, следуйте инструкциям для создания бота
  3. Скопируйте токен бота (формат: 123456789:ABCdef...)
  4. В Mockarty Админ → Каналы → Добавить → Telegram:
    • Bot Token: вставьте токен
    • Bot Username: @YourBotName (опционально, для отображения)
  5. Сохраните и включите

Пользователи подключатся нажав deeplink, который откроет бота в Telegram.

Slack

Вариант А: Bot Token (рекомендуется для личных сообщений)

  1. Перейдите на api.slack.com/apps → Create New App
  2. Добавьте Bot Token Scopes: chat:write, users:read.email
  3. Установите в workspace, скопируйте Bot Token (xoxb-...)
  4. В Mockarty: вставьте как Bot Token

Пользователи вводят свой email Slack для получения DM.

Вариант Б: Incoming Webhook (уровень канала)

  1. В Slack App → Incoming Webhooks → Add New Webhook
  2. Выберите канал, скопируйте URL
  3. В Mockarty: вставьте как Webhook URL

Discord

  1. В Discord: Настройки сервера → Интеграции → Вебхуки → Создать вебхук
  2. Выберите канал, скопируйте URL вебхука
  3. В Mockarty: вставьте как Webhook URL

Привязка к пользователю не нужна — сообщения идут в канал.

Microsoft Teams

  1. В канале Teams: нажмите ... → Workflows
  2. Выберите “Post to a channel when a webhook request is received”
  3. Пройдите мастер настройки, скопируйте URL
  4. В Mockarty: вставьте как Webhook URL

Примечание: Старые URL коннекторов Office 365 выводятся из эксплуатации. Используйте Workflows (Power Automate).

PagerDuty

  1. В PagerDuty: Services → выберите сервис → вкладка Integrations
  2. Add Integration → Events API v2
  3. Скопируйте Integration Key
  4. В Mockarty: вставьте как Integration Key (routing_key)
  5. Опционально: укажите Severity — одно из critical, error, warning, info (если не указано, применяется значение по умолчанию для типа события)

OpsGenie

  1. В OpsGenie: Teams → выберите команду → Integrations → Add integration → API
  2. Скопируйте API Key
  3. В Mockarty: вставьте как API Key
  4. Выберите Region — us (api.opsgenie.com) или eu (api.eu.opsgenie.com). Неверный регион приводит к молчаливым сбоям доставки.

Тестирование канала

После сохранения нажмите кнопку Test на любом канале, чтобы отправить тестовое уведомление. Для каналов, требующих получателя (Telegram, Slack), потребуется указать chat ID или email.

Настройка пользователем

Подключение к каналам

  1. Перейдите в Настройки → Мои каналы уведомлений
  2. Доступные каналы от администратора отображаются в Доступные каналы
  3. Нажмите Подключить на нужном канале

Подключение Telegram

  1. Нажмите Подключить на канале Telegram
  2. Откроется deeplink — нажмите, чтобы перейти к боту в Telegram
  3. Нажмите Start в чате с ботом
  4. Подключение подтверждается автоматически

Подключение Slack

  1. Нажмите Подключить на канале Slack
  2. Введите ваш email в workspace Slack
  3. Mockarty найдёт ваш Slack ID и будет отправлять DM напрямую

Webhook-каналы (Discord, Teams и др.)

Эти каналы настраиваются на уровне канала — нажмите Подключить, и всё готово. Все пользователи, подключённые к одному и тому же каналу, получают одинаковые сообщения.

Матрица предпочтений

После подключения настройте, какие события вызывают уведомления:

ID события Описание
agent.task.completed AI-агент успешно завершил задачу
agent.task.failed Задача AI-агента завершилась с ошибкой
test.run.completed Прогон коллекции API-тестов завершён
test.run.failed Прогон коллекции API-тестов провалился
perf.test.completed Нагрузочный / performance-тест завершён
perf.test.threshold_breach Performance-тест превысил SLO-порог (latency, error rate, throughput)
fuzzing.finding.new Фаззер обнаружил новую уязвимость или аномалию
contract.drift.detected Обнаружен дрейф контракта между записанным и live-ответом
system.incident.triggered Системный инцидент (сбой очистки, проблема с лицензией, исчерпание ресурсов)

Используйте чекбоксы в матрице предпочтений для включения/отключения каждого события по каждому каналу. Указанные ID — это канонические идентификаторы, которые эмитятся в EventBus и используются движком шаблонов.

Интеграция с AI-агентом

AI-агент (сабагент-нотификатор) может отправлять уведомления через системные каналы без credentials:

  1. list_system_channels — возвращает доступные каналы с ID
  2. send_via_channel — отправляет уведомление через канал по ID

Пример диалога с агентом:

Пользователь: "Отправь сводку результатов тестов за сегодня в Slack"
Агент: [вызывает list_system_channels → находит канал Slack]
Агент: [вызывает send_via_channel с channel_id, title, text]

Без AI-агента

Система уведомлений полностью работает без AI-агента:

  • Автоматические уведомления: События (завершение тестов, аномалии фаззинга и т.д.) автоматически рассылаются через EventBus → Channel Dispatcher
  • Предпочтения пользователя: Управляйте маршрутизацией через матрицу предпочтений
  • Администраторские рассылки: Админ может тестировать каналы прямо из админ-панели

API Endpoints

API администратора

Метод Endpoint Описание
GET /api/v1/admin/channels Список всех каналов
GET /api/v1/admin/channels/types Поддерживаемые типы каналов
POST /api/v1/admin/channels Создать канал
PUT /api/v1/admin/channels/:id Обновить канал
DELETE /api/v1/admin/channels/:id Удалить канал
POST /api/v1/admin/channels/:id/test Тестировать канал
GET /api/v1/admin/channel-delivery/dlq Список недоставленных сообщений
GET /api/v1/admin/channel-delivery/retry-queue Очередь ожидающих повторов
POST /api/v1/admin/channel-delivery/dlq/:id/requeue Вернуть запись из DLQ в очередь повторов
GET /api/v1/admin/channel-templates Список шаблонов сообщений канала
POST /api/v1/admin/channel-templates Создать/обновить шаблон сообщения
DELETE /api/v1/admin/channel-templates/:id Удалить переопределение шаблона
POST /api/v1/admin/channel-templates/preview Отрендерить шаблон на тестовом payload без сохранения
GET /api/v1/admin/channel-templates/snippets Каталог готовых сниппетов для редактора шаблонов
GET /api/v1/notifications/catalog Каталог зарегистрированных типов событий (используется UI-роутером)

Надёжность доставки

Каждая попытка доставки записывается в channel_delivery_log со статусом, который проходит путь pending → delivered или pending → retrying → dead_letter при исчерпании max_retries. В админ-панели Каналы уведомлений → Журнал доставки доступны две вкладки:

  • Недоставленные – доставки, которые использовали все попытки. Одним кликом можно вернуть запись обратно в очередь повторов.
  • Очередь повторов – доставки, ожидающие следующей попытки, отсортированные по next_retry_at.

Фоновый worker, работающий только на лидер-ноде, забирает из очереди просроченные записи, применяет экспоненциальную задержку и переводит строку в dead_letter как только retry_count >= max_retries.

Шаблоны сообщений по типам событий

Диспетчер рендерит каждое уведомление через шаблонный движок с поддержкой переопределений. Порядок поиска (от самого конкретного к наименее):

  1. (eventType, channelType, lang) – полностью конкретное переопределение
  2. (eventType, channelType, "") – любой язык
  3. (eventType, "", lang) – любой канал
  4. (eventType, "", "") – любой канал, любой язык
  5. Встроенное значение по умолчанию из кода

Шаблоны используют синтаксис Go text/template и имеют доступ к исходному payload события ({{ .Payload.fieldName }}), заголовку ({{ .Title }}), телу ({{ .Body }}) и глубокой ссылке ({{ .Link }}).

Переопределения управляются через Каналы уведомлений → Шаблоны сообщений в админ-интерфейсе или напрямую через endpoints /api/v1/admin/channel-templates.

API пользователя

Метод Endpoint Описание
GET /api/v1/channels Доступные каналы
GET /api/v1/channels/bindings Мои привязки
POST /api/v1/channels/bindings Подключиться к каналу
PUT /api/v1/channels/bindings/:id Обновить привязку
DELETE /api/v1/channels/bindings/:id Отключиться
POST /api/v1/channels/telegram/connect Получить deeplink Telegram
GET /api/v1/channels/preferences Получить предпочтения
PUT /api/v1/channels/preferences Обновить предпочтение

Смотрите также

Предыдущая
База знаний (RAG)