Microsoft Graph Webhook Listener | Easy Understand Hermes Agent

Piénsalo así: en lugar de que tu teléfono esté revisando constantemente la nevera para ver si falta leche, la nevera te envía un mensaje en el momento justo en que se acaba. Eso es exactamente lo que hace un listener de webhook: espera una señal y reacciona automáticamente.

¿Qué Hace Realmente Esto?

El Listener de Webhook de Microsoft Graph es una función de Hermes Agent que permite que Microsoft 365 (M365) avise a Hermes cuando algo ocurre — como que termine una reunión de Teams, que llegue un nuevo mensaje de chat o que se actualice un evento del calendario.

No es un chatbot con el que hables. Es más bien un asistente silencioso que escucha las “notificaciones de cambio” de Microsoft Graph y luego activa un pipeline para hacer algo útil — como obtener la transcripción de una reunión y publicar un resumen de vuelta en Teams.

Lo Que Necesitas Antes de Empezar

Necesitarás tres cosas:

Credenciales de una app de Microsoft Graph — registra una aplicación en el portal de Azure de Microsoft.
Una URL HTTPS pública — Microsoft Graph no llamará a localhost. Un túnel de desarrollo sirve para probar; un dominio real es lo mejor para producción.
Un secreto fuerte — este es tu valor clientState, que se usa para verificar que las notificaciones realmente provienen de Microsoft.

Genera un secreto con:

openssl rand -hex 32

Ponlo en ~/.hermes/.env así:

MSGRAPH_WEBHOOK_CLIENT_STATE=tu-secreto-generado-aqui

Configuración Rápida de Inicio

La forma más sencilla de activar el listener es con un archivo de configuración mínimo (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "reemplaza-con-un-secreto-fuerte"
      accepted_resources:
        - "communications/onlineMeetings"

O usa variables de entorno en ~/.hermes/.env (se combinan automáticamente al iniciar):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=tu-secreto-generado-aqui
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Nota: El host de enlace solo se lee desde extra.host en el archivo de configuración — no existe una variable de entorno MSGRAPH_WEBHOOK_HOST para sobrescribirlo.

Iniciando el Listener

Ejecuta este comando para iniciar la puerta de enlace:

hermes gateway run

Una vez en ejecución, el listener expone estos endpoints:

POST /msgraph/webhook — recibe notificaciones de cambio de Microsoft Graph
GET /msgraph/webhook?validationToken=... — gestiona el handshake de validación de la suscripción
GET /health — una sonda de disponibilidad con contadores de notificaciones aceptadas/duplicadas

Haciéndolo Público

Para que Microsoft Graph pueda alcanzar tu listener, necesitas exponerlo públicamente. Usa un proxy inverso, un túnel de desarrollo o un ingress. Tu URL de notificación para las suscripciones de Graph será:

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

Hoja de Referencia de Configuración

Todos los ajustes viven bajo platforms.msgraph_webhook.extra:

Ajuste	Valor por defecto	Qué Hace
`host`	sin definir (todas las interfaces)	Dirección de enlace. Usa `127.0.0.1` para túneles de desarrollo.
`port`	`8646`	Puerto de escucha.
`webhook_path`	`/msgraph/webhook`	Ruta donde Graph hace los POST.
`health_path`	`/health`	Endpoint de disponibilidad.
`client_state`	—	Tu secreto compartido, comparado de forma segura.
`accepted_resources`	`[]` (acepta todo)	Lista blanca de rutas de recursos de Graph. Usa `*` para comodines.

Resumen y Consejo Práctico

El Listener de Webhook de Microsoft Graph es tu puente entre los eventos de M365 y las acciones de Hermes. No es complicado — solo un listener esperando una señal para luego activar un flujo de trabajo.

Consejo práctico: Empieza con accepted_resources limitado a un solo recurso (como communications/onlineMeetings) para mantener las cosas simples. Una vez que veas fluir las notificaciones, amplía la lista. Y usa siempre un client_state generado correctamente — es tu apretón de manos de seguridad con Microsoft.