Webhooks: обработка входящих событий

Что такое webhooks в Hermes Agent

Webhook — это входящий HTTP POST-запрос от внешнего сервиса, который запускает агента Hermes с содержимым запроса. Внешний сервис отправляет POST на URL /webhooks/<name>, и Hermes автоматически запускает агента, обрабатывающего этот запрос.

Webhooks позволяют интегрировать Hermes с любыми внешними системами — CI/CD, мониторингом, CRM, IoT-устройствами и другими сервисами, которые поддерживают отправку HTTP-уведомлений.

Команды управления webhooks

Создание подписки

hermes webhook subscribe NAME

Создаёт маршрут /webhooks/<name>. Внешние сервисы смогут отправлять POST-запросы на этот URL, и Hermes будет запускать агента для их обработки.

Просмотр подписок

hermes webhook list

Показывает все активные webhook-подписки с их маршрутами и параметрами.

Удаление подписки

hermes webhook remove NAME

Удаляет маршрут и останавливает обработку входящих запросов для указанного webhook.

Тестирование webhook

hermes webhook test NAME

Отправляет тестовый POST-запрос на указанный webhook для проверки работоспособности маршрута.

Как работают webhooks

Процесс обработки входящего webhook-запроса:

Внешний сервис (например, GitHub, Grafana, Stripe) отправляет HTTP POST на https://your-server/webhooks/<name>

Hermes получает запрос и извлекает заголовки и тело (JSON)

Запускается агент с промптом, содержащим данные из webhook-запроса

Агент обрабатывает данные и выполняет нужные действия (уведомление, создание задачи, отправка ответа)

Формат входящего payload

Webhook принимает POST-запросы с JSON-телом. Пример payload:

{
  "event": "push",
  "repository": "my-project",
  "branch": "main",
  "commits": [
    {
      "message": "feat: add new feature",
      "author": "developer"
    }
  ],
  "timestamp": "2026-07-22T10:30:00Z"
}

Hermes также передаёт агенту HTTP-заголовки запроса, что позволяет проверять подписи и аутентификацию.

Практические сценарии использования

CI/CD уведомления

Настройте GitHub Actions, GitLab CI или Jenkins отправлять уведомления о результатах сборок и деплоев. Hermes может проанализировать логи ошибок и отправить краткое резюме в Telegram.

# GitHub webhook на /webhooks/ci
hermes webhook subscribe ci

Мониторинг и алерты

Интеграция с Grafana, Prometheus Alertmanager или Uptime Robot — Hermes получает алерты, классифицирует их по серьёзности и уведомляет команду.

CRM и автоматизация продаж

Stripe, HubSpot или AmoCRM могут отправлять события о новых лидах, оплатах или изменениях статуса сделок. Hermes обрабатывает события и создаёт задачи или обновляет записи.

IoT и датчики

Датчики умного дома или промышленные системы отправляют показания — Hermes анализирует данные и принимает решения (уведомление при аномалиях, автоматическое управление).

Безопасность webhook-ов

Для защиты webhook-маршрутов от несанкционированного доступа рекомендуется:

Использовать сложные и уникальные имена маршрутов — не /webhooks/test, а /webhooks/gh-abc123-secret

Проверять подписи запросов (X-Hub-Signature для GitHub, Stripe-Signature для Stripe) в промпте агента

Ограничивать доступ через файрвол — разрешить входящие запросы только от IP-адресов сервисов

Использовать HTTPS для шифрования трафика

FAQ

Какой URL использовать для webhook?

URL формируется как https://your-hermes-server/webhooks/<name>, где <name> — имя, указанное при создании подписки через hermes webhook subscribe.

Какие HTTP-методы поддерживаются?

Только POST. GET-запросы на webhook-маршрут возвращают информацию о подписке.

Можно ли обрабатывать файлы из webhook?

Webhook принимает JSON-body. Для обработки файлов агент может скачать их по ссылке из payload с помощью инструментов работы с сетью.

Что происходит, если агент занят?

Webhook-запросы обрабатываются параллельно. Если агент занят предыдущим запросом, новый запускается в отдельной сессии.