5. El webhook

Hasta ahora consultamos health enviando un GET. Vamos a invertir esa iniciativa para que GitHub nos avise cuando ocurre algo. Con polling, un cliente pregunta periódicamente si hay novedades, aunque nada haya cambiado. Con un webhook, GitHub envía una solicitud HTTP POST cuando ocurre un evento seleccionado. Ese POST lleva los datos del aviso al receptor. El túnel sólo transporta la request y el receptor la valida y responde.

Para seguir, comprobá que el túnel hacia Next funciona y que tenés tu repositorio privado y el perfil del agente conservado. Vamos a usar el navegador de GitHub, el host en la carpeta lab y los containers existentes lab-agent y lab-app.

En este capítulo vamos a recibir en POST /api/github, implementado en app/api/github/route.ts. No se llama a Hermes ni se ejecuta código del PR. Buscamos reconocer una entrega real pull_request, encontrarla también en los logs y repetirla para observar si el proceso recuerda su ID. Al terminar dejaremos inactivo sólo este hook antes de cambiar de receptor.

El diagrama del taller es conceptual. La respuesta HTTP confirma la recepción del aviso, no una revisión de código.

Los encabezados, o headers, describen la solicitud; el body lleva sus datos en JSON. El evento indica qué tipo de cambio ocurrió, por ejemplo pull_request. La propiedad action del JSON precisa qué pasó dentro de ese tipo, como opened al abrir un PR o synchronize al actualizarlo con commits.

El secret compartido no va en la URL ni en código cliente. HTTPS cifra el transporte, pero no reemplaza la firma ni los filtros que vamos a configurar. El túnel expone el servicio completo de destino.

Empezá por autenticar GitHub dentro del agente. La sesión del host no se comparte con el container.

Referencia: crear webhooks en GitHub.