Webhook уведомлений почтовой ноды

Что отправляет webhook

Webhook передаёт во внешнюю систему каждое новое уведомление, которое появляется в панели ноды после включения интеграции

Он подходит для собственного обработчика, системы мониторинга, автоматизации или промежуточного сервиса, который отправляет сообщения в нужный мессенджер

Webhook не передаёт письма, вложения, пароли почтовых аккаунтов и содержимое почтовых ящиков

Текст уведомления и details могут содержать домен, адрес почтового ящика, IP сервера или hostname источника импорта. Считайте payload конфиденциальными операционными данными

Как подключить endpoint

После сохранения панель показывает только hostname endpoint. Полный URL повторно не возвращается и остаётся пустым в поле редактирования

Ключ подписи после сохранения тоже не возвращается. Чтобы оставить текущий endpoint и ключ без изменений, сохраните форму с пустыми полями. При замене URL обязательно создайте новый отличающийся ключ. Чтобы заменить только ключ, заполните его поле. Чтобы отключить доставку, выключите переключатель

1. 1

   Войдите в панель с ролью владельца

2. 2

   Откройте «Сервер» → «Настройки системы»

3. 3

   Включите «Webhook уведомлений»

4. 4

   Укажите полный HTTPS URL обработчика

5. 5

   Сгенерируйте ключ подписи и скопируйте его в конфигурацию обработчика до сохранения формы

6. 6

   Сохраните настройки

7. 7

   Создайте контролируемое уведомление и проверьте журнал запросов своего обработчика

Требования к endpoint

Перед каждым соединением система заново разрешает DNS-имя и подключается только к публичному IP. Это правило защищает ноду от перенаправления запросов во внутреннюю сеть через DNS rebinding

Path и query string разрешены для маршрутизации, но не должны содержать пароли, токены и другие секреты. Подлинность запроса подтверждает отдельная HMAC-подпись

HTTP-запрос

Проверка подписи запроса

Точное подписываемое значение: v1\n{unix_timestamp}\n{event_id}\n{raw_body}. Последняя часть — исходные байты HTTP-тела без завершающего перевода строки, если его не было в запросе

Ключ в панели представлен 43 символами base64url без padding и после декодирования содержит ровно 32 байта. Для HMAC используйте декодированные байты, а не текст из поля

Каждая повторная попытка получает новый timestamp и подпись, но сохраняет прежний event_id. Ограничение времени защищает от позднего replay, а уникальность event_id — от повторного выполнения принятого события

1. 1

   Получите исходные байты тела без предварительного разбора JSON и преобразования кодировки

2. 2

   Проверьте, что X-Svoimail-Webhook-Timestamp содержит целое Unix-время и отличается от текущего времени не более чем на 5 минут

3. 3

   Составьте подписываемое значение из v1, timestamp, event ID и исходного тела, разделяя первые три части переводом строки \n

4. 4

   Вычислите HMAC-SHA-256 с 256-битным ключом, полученным при настройке webhook

5. 5

   Сравните ожидаемое значение v1={hex} с X-Svoimail-Webhook-Signature функцией сравнения с постоянным временем

6. 6

   Только после успешной проверки подписи разбирайте JSON, проверяйте поля события и выполняйте действие

Типы событий

Версия 1 использует только перечисленные значения. Неизвестный переход мониторинга безопасно отправляется как notification.created

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

Поля payload версии 1

Пример события мониторинга

{
  "version": 1,
  "event_id": "notification-1842",
  "event_type": "monitoring.incident.opened",
  "occurred_at": "2026-10-15T08:45:12.381Z",
  "severity": "warning",
  "category": "monitoring",
  "title": "Очередь Postfix требует внимания",
  "message": "В отложенной очереди Postfix находится 128 сообщений",
  "resource": {
    "type": "service",
    "id": "postfix"
  },
  "details": {
    "check_key": "postfix.queue.backlog",
    "health_status": "firing",
    "transition": "opened",
    "incident_sequence": 3,
    "incident_severity": "warning",
    "failure_streak": 2,
    "failure_threshold": 2,
    "recovery_streak": 0,
    "recovery_threshold": 2,
    "first_failed_at": "2026-10-15T08:44:12.381Z",
    "observed_at": "2026-10-15T08:45:12.381Z",
    "details": {
      "total_count": 136,
      "deferred_count": 128,
      "oldest_deferred_age_seconds": 16200
    }
  }
}

Поля details для мониторинга

Ключи встроенных проверок

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

Пороги и данные встроенных проверок

Как система обрабатывает HTTP-статусы

Заголовок Retry-After не изменяет расписание повторов: worker использует фиксированные интервалы из раздела ниже

Внутренние статусы доставки

Статусы являются частью серверного механизма надёжности и не требуют ручного управления в панели

Расписание повторных попыток

После шестой временной ошибки доставка получает статус failed

Если worker остановился во время запроса и остались попытки, временная аренда истекает через минуту и запись снова становится доступной для обработки

Гарантия доставки и дедупликация

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

Используется гарантия at-least-once. Если endpoint принял запрос, а worker остановился до сохранения результата, тот же запрос может прийти повторно

Для дедупликации сохраните event_id с уникальным ограничением и при повторном значении верните успешный 2xx без повторного выполнения действия

Если один обработчик принимает события нескольких нод, используйте отдельный route для каждой ноды и уникальность по паре route + event_id, потому что числовые ID разных нод могут совпасть

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

Минимальные требования к обработчику

• Принимать только POST с Content-Type: application/json

• Проверять timestamp и HMAC-подпись по исходным байтам тела до разбора JSON

• Проверять version до разбора полей конкретной версии

• Ограничить размер тела запроса на своей стороне

• Сохранять event_id и не выполнять одно действие дважды

• Возвращать 2xx после сохранения события, а не после долгой отправки во внешние сервисы

• Игнорировать неизвестные дополнительные поля

• Записывать время, event_id, event_type и итог обработки без полного URL endpoint

• Отвечать без секретов, stack trace и внутренних данных

Безопасность endpoint

Полный URL и ключ подписи хранятся на ноде в зашифрованном виде с разным контекстом шифрования. В API и после сохранения в панели возвращаются только признак настройки и hostname

Версия 1 подписывает timestamp, event ID и точные байты тела алгоритмом HMAC-SHA-256. Проверяйте подпись до разбора JSON и используйте сравнение с постоянным временем

Не добавляйте логин и пароль через user:password@host: такой формат отклоняется. Не размещайте секреты в path или query string и исключите полный URL из журналов reverse proxy

Передавайте события только в доверенную систему, которая хранит payload и журналы с учётом содержащихся в них доменов, адресов ящиков, IP и других операционных данных

Ограничьте права получателя: webhook должен создавать уведомление или запись, но не должен получать административный доступ к почтовой ноде

Что происходит при замене и отключении

Новый URL вместе с новым ключом или отдельно заменённый ключ применяется только к уведомлениям, созданным после сохранения настройки

При замене URL или ключа незавершённые доставки со старой конфигурацией получают статус cancelled и не переносятся на новый endpoint

Запрос, уже отправленный в момент изменения настройки, может завершиться со старым URL или ключом. Получатель всё равно должен выполнять дедупликацию по event_id

После отключения новые уведомления продолжают появляться в панели, но записи webhook-доставки для них не создаются

Проверка при отсутствии событий

1. 1

   Убедитесь, что переключатель webhook включён и панель показывает ожидаемый hostname

2. 2

   Проверьте доступность HTTPS endpoint из интернета и срок действия его сертификата

3. 3

   Убедитесь, что endpoint не отвечает redirect и сразу обрабатывает исходный URL

4. 4

   Проверьте, что обработчик укладывается в 10 секунд

5. 5

   Проверьте журнал получателя по заголовку X-Svoimail-Event-ID

6. 6

   Для временной ошибки возвращайте 408, 425, 429 или 5xx, для принятого события возвращайте 2xx

7. 7

   После исправления создайте новое контролируемое уведомление и проверьте результат