Webhooks — Entrada Universal de Eventos | Easy Understand Hermes Agent

Webhooks — Entrada Universal de Eventos

Imagina esto: un desarrollador abre un pull request en GitHub y, en cuestión de segundos, tu agente de IA ya ha revisado el código y ha publicado un comentario. O un pago falla en Stripe y tu agente notifica automáticamente a tu equipo en Telegram. Esa es la magia de los webhooks: permiten que servicios externos llamen a la puerta de tu agente y digan: “Oye, acaba de pasar algo, ocúpate de ello”.

¿Qué Son los Webhooks?

Los webhooks son como un timbre para tus aplicaciones. En lugar de estar comprobando constantemente si algo ha cambiado (polling), simplemente esperas a que suene el timbre. Cuando GitHub, GitLab, JIRA, Stripe o cualquier otro servicio envía una petición HTTP POST a tu endpoint de webhook, tu agente Hermes se despierta, procesa el evento y actúa.

¿La mejor parte? Tu agente puede responder de muchas maneras: publicando comentarios en PRs, enviando mensajes a Telegram o Discord, o simplemente registrando el resultado para revisarlo más tarde.

Inicio Rápido

Empezar es sorprendentemente sencillo:

Activa el adaptador de webhooks mediante hermes gateway setup o variables de entorno
Define rutas en config.yaml o créalas dinámicamente con hermes webhook subscribe
Apunta tu servicio a http://tu-servidor:8644/webhooks/<nombre-de-ruta>

Y listo. Tu agente ya está de guardia.

Configuración del Gateway

Tienes dos formas de activar los webhooks, elige la que te resulte más cómoda.

Opción 1: El Asistente de Configuración

hermes gateway setup

Sigue las indicaciones para activar los webhooks, elegir un puerto y establecer un secreto HMAC global. El asistente se encarga de toda la configuración aburrida por ti.

Opción 2: Variables de Entorno

Añade estas líneas a ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # valor por defecto
WEBHOOK_SECRET=tu-secreto-global

Una vez que el gateway esté en marcha, verifica que está vivo:

curl http://localhost:8644/health

Deberías ver:

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

Configuración de Rutas

Las rutas son el corazón del manejo de webhooks. Cada ruta le indica a tu agente cómo lidiar con eventos de una fuente específica. Piénsalo como instrucciones personalizadas para diferentes tipos de visitantes.

Esto es lo que puedes configurar por ruta:

Propiedad	Qué hace
`events`	Qué tipos de eventos aceptar (p. ej., `["pull_request"]`). Déjalo vacío para aceptarlo todo.
`secret`	Secreto HMAC para validación de firmas. Usa `"INSECURE_NO_AUTH"` solo para pruebas.
`profile`	Qué perfil puede ejecutar esta ruta (útil con multiplexación).
`prompt`	Plantilla de texto usando notación de puntos como `{pull_request.title}`. Omítelo para volcar el payload JSON completo.
`filters`	Condiciones declarativas para ignorar payloads no deseados antes de que el agente se ejecute.
`script`	Un script de filtrado/transformación que puede modificar el payload antes del templating.
`skills`	Qué habilidades cargar para esta ejecución del agente.
`toolsets`	Qué herramientas puede usar el agente (reemplaza el toolset de webhook predeterminado).
`deliver`	Dónde enviar la respuesta: `github_comment`, `telegram`, `discord`, `slack`, `log`, y más.
`deliver_extra`	Detalles adicionales de entrega como nombre del repositorio o ID del chat.
`deliver_only`	Omite al agente por completo y entrega el prompt renderizado tal cual. ¡Costo de LLM cero!

Un Ejemplo del Mundo Real

Veamos una configuración práctica. Aquí tienes una ruta que revisa pull requests:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "secreto-fallback-global"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "secreto-webhook-github"
          prompt: |
            Revisa este pull request:
            Repositorio: {repository.full_name}
            PR #{number}: {pull_request.title}
            Autor: {pull_request.user.login}
            URL: {pull_request.html_url}
            URL del diff: {pull_request.diff_url}
            Acción: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Y aquí tienes una ruta que envía una notificación a Telegram solo cuando alguien hace push a la rama principal:

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

Filtrado Inteligente

La función filters es especialmente útil. Los proveedores suelen enviar una avalancha de eventos, pero a ti solo te importan unos pocos. Los filtros te permiten ignorar el ruido antes de que tu agente siquiera se despierte. Los payloads que no coinciden reciben una respuesta educada de {"status":"ignored","reason":"filter"} con HTTP 200 — sin cómputo desperdiciado, sin llamadas innecesarias al LLM.

Modo de Entrega Directa

Aquí tienes un truco ingenioso: activa deliver_only: true y tu agente no se ejecuta en absoluto. La plantilla del prompt renderizada se convierte en el mensaje literal que se entrega. Esto significa entrega en menos de un segundo con costo de LLM cero. Perfecto para notificaciones simples que no necesitan razonamiento de IA.

Nota de Seguridad

Recuerda: autenticado no significa confiable. Los campos del payload de los webhooks son datos no confiables. Siempre valida y sanitiza cualquier cosa que uses en prompts o plantillas. Tu agente debería tratar el contenido de los webhooks como entrada de usuario — con escepticismo saludable.

Conclusión

Los webhooks convierten a tu agente Hermes en un asistente receptivo que reacciona al mundo en tiempo real. Ya sea que estés automatizando revisiones de código, enviando notificaciones de despliegue o construyendo flujos de trabajo complejos basados en eventos, el adaptador de webhooks lo hace todo posible con solo unas pocas líneas de YAML.