Webhooks — универсальная точка входа для событий

Представьте: разработчик открывает pull request на GitHub, и через несколько секунд ваш AI-агент уже проверил код и оставил комментарий. Или оплата на Stripe не прошла, и ваш агент автоматически уведомляет команду в Telegram. Это и есть магия вебхуков — они позволяют внешним сервисам постучаться в дверь вашего агента и сказать: «Эй, только что кое-что произошло, разберись, пожалуйста».

Что такое вебхуки?

Вебхуки — это как дверной звонок для ваших приложений. Вместо того чтобы постоянно проверять, не изменилось ли что-то (поллинг), вы просто ждёте, когда звонок зазвонит. Когда GitHub, GitLab, JIRA, Stripe или любой другой сервис отправляет HTTP POST-запрос на ваш вебхук-эндпоинт, ваш агент Hermes просыпается, обрабатывает событие и принимает меры.

Самое приятное? Ваш агент может реагировать множеством способов — оставлять комментарии к PR, отправлять сообщения в Telegram или Discord или просто логировать результат для последующего просмотра.

Быстрый старт

Начать на удивление просто:

Включите вебхук-адаптер через hermes gateway setup или переменные окружения
Определите маршруты в config.yaml или создайте их динамически с помощью hermes webhook subscribe
Укажите вашему сервису адрес http://your-server:8644/webhooks/<имя-маршрута>

Всё. Ваш агент теперь на связи.

Настройка шлюза

У вас есть два способа включить вебхуки — выбирайте, что удобнее.

Вариант 1: Мастер настройки

hermes gateway setup

Следуйте подсказкам, чтобы включить вебхуки, выбрать порт и задать глобальный HMAC-секрет. Мастер возьмёт на себя всю скучную настройку.

Вариант 2: Переменные окружения

Добавьте эти строки в ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # по умолчанию
WEBHOOK_SECRET=your-global-secret

Когда шлюз запущен, проверьте, что он жив:

curl http://localhost:8644/health

Вы должны увидеть:

{"status": "ok", "platform": "webhook"}

Настройка маршрутов

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

Вот что можно настроить для каждого маршрута:

Свойство	Что делает
`events`	Какие типы событий принимать (например, `["pull_request"]`). Оставьте пустым, чтобы принимать всё.
`secret`	HMAC-секрет для проверки подписи. Используйте `"INSECURE_NO_AUTH"` только для тестирования.
`profile`	Какой профиль может выполнять этот маршрут (полезно при мультиплексировании).
`prompt`	Шаблонная строка с точечной нотацией, например `{pull_request.title}`. Опустите, чтобы выгрузить полный JSON-пейлоад.
`filters`	Декларативные условия для игнорирования ненужных пейлоадов до запуска агента.
`script`	Скрипт фильтрации/трансформации, который может изменить пейлоад перед шаблонизацией.
`skills`	Какие навыки загружать для этого запуска агента.
`toolsets`	Какие инструменты может использовать агент (заменяет стандартный вебхук-тулсет).
`deliver`	Куда отправлять ответ: `github_comment`, `telegram`, `discord`, `slack`, `log` и другие.
`deliver_extra`	Дополнительные детали доставки, например имя репозитория или ID чата.
`deliver_only`	Полностью пропустить агента и доставить отрендеренный промпт как есть. Нулевая стоимость LLM!

Пример из реального мира

Давайте посмотрим на практическую настройку. Вот маршрут, который проверяет pull request:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

А вот маршрут, который отправляет уведомление в Telegram только когда кто-то пушит в основную ветку:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Умная фильтрация

Функция filters особенно удобна. Провайдеры часто шлют поток событий, а вам нужны лишь некоторые. Фильтры позволяют игнорировать шум ещё до того, как агент проснётся. Неподходящие пейлоады получают вежливый ответ {"status":"ignored","reason":"filter"} с HTTP 200 — никакой потраченной впустую вычислительной мощности, никаких лишних вызовов LLM.

Режим прямой доставки

Вот хитрый приём: установите deliver_only: true — и агент вообще не запускается. Отрендеренный шаблон промпта становится буквальным сообщением, которое доставляется. Это означает доставку за доли секунды с нулевой стоимостью LLM. Идеально для простых уведомлений, которым не нужен AI-анализ.

Заметка о безопасности

Помните: аутентифицированный не значит доверенный. Поля пейлоада из вебхуков — это недоверенные данные. Всегда проверяйте и очищайте всё, что используете в промптах или шаблонах. Ваш агент должен относиться к содержимому вебхуков как к пользовательскому вводу — со здоровым скептицизмом.

Суть

Вебхуки превращают вашего агента Hermes в отзывчивого ассистента, который реагирует на мир в реальном времени. Автоматизируете ли вы проверку кода, отправляете уведомления о деплое или строите сложные событийно-ориентированные рабочие процессы — вебхук-адаптер делает всё это возможным всего несколькими строками YAML.