Платформы Обмена Сообщениями Hermes

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

Что это вообще делает?

Microsoft Graph Webhook Listener — это функция в Hermes Agent, которая позволяет Microsoft 365 (M365) сообщать Hermes о том, что что-то произошло — например, завершилось собрание в Teams, пришло новое сообщение в чате или обновилось событие календаря.

Это не чат-бот, с которым вы общаетесь. Это скорее тихий помощник, который прислушивается к «уведомлениям об изменениях» от Microsoft Graph, а затем запускает пайплайн для выполнения полезной задачи — например, получения расшифровки собрания и публикации краткого отчёта обратно в Teams.

Что нужно перед началом работы

Вам понадобятся три вещи:

Учётные данные приложения Microsoft Graph — зарегистрируйте приложение на портале Azure.
Публичный HTTPS-URL — Microsoft Graph не будет вызывать localhost. Для тестирования подойдёт dev-туннель; для продакшена лучше использовать реальный домен.
Надёжный секрет — это ваше значение clientState, используемое для проверки того, что уведомления действительно приходят от Microsoft.

Сгенерируйте секрет с помощью:

openssl rand -hex 32

Поместите его в ~/.hermes/.env вот так:

MSGRAPH_WEBHOOK_CLIENT_STATE=ваш-сгенерированный-секрет

Быстрая настройка

Самый простой способ включить слушатель — использовать минимальный конфигурационный файл (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "замените-на-надёжный-секрет"
      accepted_resources:
        - "communications/onlineMeetings"

Или используйте переменные окружения в ~/.hermes/.env (они автоматически объединяются при запуске):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=ваш-сгенерированный-секрет
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Примечание: Адрес привязки считывается только из extra.host в конфигурационном файле — переменной окружения MSGRAPH_WEBHOOK_HOST для переопределения не существует.

Запуск слушателя

Выполните эту команду для запуска шлюза:

hermes gateway run

После запуска слушатель предоставляет следующие конечные точки:

POST /msgraph/webhook — принимает уведомления об изменениях от Microsoft Graph
GET /msgraph/webhook?validationToken=... — обрабатывает проверочное рукопожатие при подписке
GET /health — проверка готовности со счётчиками принятых/дублирующихся уведомлений

Делаем его публичным

Чтобы Microsoft Graph мог связаться с вашим слушателем, его необходимо сделать публичным. Используйте обратный прокси, dev-туннель или ingress. URL вашего уведомления для подписок Graph будет выглядеть так:

https://ops.example.com/msgraph/webhook

Шпаргалка по настройке

Все настройки находятся в разделе platforms.msgraph_webhook.extra:

Настройка	По умолчанию	Что делает
`host`	не задан (все интерфейсы)	Адрес привязки. Используйте `127.0.0.1` для dev-туннелей.
`port`	`8646`	Порт для прослушивания.
`webhook_path`	`/msgraph/webhook`	Путь, на который Graph отправляет POST-запросы.
`health_path`	`/health`	Конечная точка проверки готовности.
`client_state`	—	Ваш общий секрет, сравнивается безопасным способом.
`accepted_resources`	`[]` (принимать все)	Белый список путей ресурсов Graph. Используйте `*` для подстановочных знаков.

Итоги и практический совет

Microsoft Graph Webhook Listener — это ваш мост между событиями M365 и действиями Hermes. Всё не так сложно — просто слушатель ждёт сигнал, а затем запускает рабочий процесс.

Практический совет: Начните с accepted_resources, ограниченного одним ресурсом (например, communications/onlineMeetings), чтобы всё было просто. Как только увидите, что уведомления приходят, расширяйте список. И всегда используйте правильно сгенерированный client_state — это ваше рукопожатие безопасности с Microsoft.