Как настроить подписанные оповещения webhook из инструмента мониторинга

Оповещения webhook — это клей интеграции, который соединяет монитор времени доступности со всем остальным: PagerDuty, Opsgenie, внутренние системы инцидентов, трекеры тикетов, пользовательские боты Slack. Базовая механика простая (ваш монитор отправляет JSON на вашу конечную точку, когда срабатывает инцидент). Детали (проверка подписи, поведение повтора, идемпотентность) — вот где реализация становится интересной. Это руководство охватывает практическую настройку.

Почему webhook вместо электронной почты или Slack

Электронная почта и Slack хорошо работают для людей. Webhook работают для систем. Три сценария использования оправдывают дополнительную настройку.

Маршрутизация на инструменты управления дежурством (PagerDuty, Opsgenie). Запуск внутренней системы управления инцидентами, которая создает заявки, потоки Slack и автоматически выполняет runbooks. Запуск автоматического восстановления (перезагрузка воркера, масштабирование кластера, переключение на резервный регион). Все три требуют структурированную полезную нагрузку, надежную доставку с повторными попытками и аутентификацию. Webhooks предоставляют все три; электронная почта и Slack не предоставляют ничего.

Структура ожидаемой полезной нагрузки

Большинство инструментов мониторинга отправляют похожую JSON-полезную нагрузку при событиях инцидентов. Точные названия полей различаются, но четыре раздела являются стандартными.

• event: « monitor.down » или « monitor.up », чтобы ваша конечная точка могла маршрутизировать открытия и закрытия.
• monitor: id, name, type, target, last status. Достаточно контекста для идентификации неработающего компонента.
• check: status code, response time, error message. Диагностические сведения.
• timestamp: ISO 8601, UTC. Важно для упорядочения и дедупликации.

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

Любая конечная точка webhook, открытая в общедоступный интернет, требует проверки подписи. Без нее злоумышленник, угадавший ваш URL, может подделать событие об отказе монитора и запустить ваше восстановление, вызов дежурного и ответ поддержки. С проверкой HMAC только ваш инструмент мониторинга может подписывать действительные полезные нагрузки.

Паттерн: инструмент мониторинга отправляет заголовок X-Monitorah-Signature с HMAC-SHA256 исходного тела запроса, где ключом служит общий секрет. Ваша конечная точка пересчитывает HMAC тела, используя тот же секрет, сравнивает (в постоянное время) со значением заголовка, отклоняет при несовпадении. Используйте исходные байты тела для HMAC, а не разобранный JSON: единственное различие в пробеле производит другую подпись.

Повторные попытки и идемпотентность

Доставка webhooks не гарантирована. Два паттерна делают вашу конечную точку устойчивой к повторным попыткам и частичным сбоям.

• Корректно обрабатывайте повторные попытки. Большинство инструментов мониторинга повторно попытаются ответить 5xx с экспоненциальной задержкой в течение 24 часов. Возвращайте 5xx, если вы не можете обработать событие; возвращайте 2xx, если вы можете.
• Используйте id события как ключ идемпотентности. Одно открытие инцидента может запустить webhook дважды во время сбоя сети. Дедублируйте, сохраняя id события и пропуская, если вы уже его обработали.
• Отвечайте быстро. Потратьте менее 5 секунд на возврат 2xx, даже если ваша нижестоящая обработка занимает больше времени. При необходимости используйте очередь заданий.

Интеграция с PagerDuty

PagerDuty принимает универсальный webhook через Events API v2. Поток: ваш инструмент мониторинга отправляет POST пользовательской JSON-полезной нагрузки вашему обработчику. Ваш обработчик проверяет HMAC, преобразует полезную нагрузку в ожидаемую PagerDuty схему и отправляет POST на конечную точку событий PagerDuty с вашим ключом маршрутизации.

Слой преобразования — это правильное место для добавления дедупликации, правил эскалации и ключей маршрутизации для каждого монитора. UI PagerDuty обрабатывает ротацию после получения события. Держите преобразователь простым. Самая чистая версия — менее ста строк кода.

Стартовый обработчик webhook в 20 строк

Шаблон: получить POST, извлечь заголовок X-Monitorah-Signature, применить HMAC-SHA256 к сырому телу с вашим общим секретом, выполнить постоянное сравнение с заголовком. Если они совпадают, разобрать JSON, дедублировать по event id, отправить. Если не совпадают, вернуть 401 без обработки. Этот обработчик — основной элемент для любой интеграции: PagerDuty, Opsgenie, Slack-боты, внутренние системы инцидентов. После его реализации любая новая интеграция — это несколько строк логики отправки и ничего больше.