Probar webhooks de GitHub en local: guía completa

Las pruebas de webhooks de GitHub en local te permiten recibir eventos de push, pull request, issue y workflow en tu máquina sin desplegar a staging. Levanta un túnel localhost, registra la URL HTTPS en los ajustes de tu GitHub App o repositorio y depura handlers con verificación de firma completa.

Por qué los webhooks de GitHub necesitan un endpoint público

GitHub entrega los eventos de webhook como peticiones HTTP POST a una URL configurada. Tu máquina local en 127.0.0.1 no es alcanzable desde los servidores de GitHub. Un túnel localhost proporciona el endpoint HTTPS público que GitHub requiere.

GitHub Apps vs webhooks de repositorio

Webhooks de repositorio

Configurados por repositorio en Settings → Webhooks. Buenos para probar los handlers de eventos de un solo repo durante el desarrollo de una funcionalidad.

Webhooks de GitHub App

Configurados a nivel de app en los ajustes de tu GitHub App. Necesarios al construir integraciones que sirven a varios repositorios u organizaciones.

Ambos tipos de entrega usan verificación de firma HMAC-SHA256 mediante la cabecera X-Hub-Signature-256.

Paso a paso: pruebas de webhooks de GitHub en local

1. Arranca tu app local con un endpoint de webhook (por ejemplo /api/webhooks/github).
2. Ejecuta npx portpreview 3000 para obtener una URL HTTPS pública.
3. En GitHub, añade la URL del túnel más la ruta del webhook como payload URL.
4. Pon el content type en application/json y selecciona los eventos a recibir.
5. Genera un secreto de webhook y guárdalo en tus variables de entorno locales.
6. Dispara eventos (haz push de un commit, abre un PR, crea un issue) e inspecciona las entregas.
7. Verifica que tu handler valida la firma y devuelve una respuesta 2xx en menos de 10 segundos.

Verificar firmas de webhooks de GitHub en local

GitHub firma cada payload con tu secreto de webhook. Tu handler debe:

• Leer el cuerpo crudo de la petición antes de parsear el JSON.
• Calcular HMAC-SHA256 usando tu secreto.
• Comparar contra la cabecera X-Hub-Signature-256 usando comparación de tiempo constante.

Las herramientas de túnel que preservan las cabeceras originales te dejan probar la ruta de verificación real. Nunca te saltes las comprobaciones de firma durante el desarrollo local.

Eventos para probar en local

• push — lógica de disparo de CI, hooks de protección de ramas, pipelines de despliegue.
• pull_request — automatización de revisión, bots de etiquetas, comprobaciones de merge.
• issues — sincronización del tracker de issues, flujos de asignación.
• installation — ciclo de vida de instalación/desinstalación de GitHub App.
• workflow_run — automatización post-CI y procesamiento de artefactos.

Depurar entregas de webhooks de GitHub fallidas

GitHub reintenta las entregas fallidas con backoff exponencial. Fallos comunes en pruebas locales:

• Timeout del handler (GitHub espera respuesta en 10 segundos).
• Firma no coincidente por parsear el cuerpo antes de la verificación.
• Sesión del túnel expirada mientras GitHub reintenta.
• Filtro de eventos equivocado: el handler recibe eventos que no procesa.

Usa el replay de webhooks para re-probar entregas fallidas sin hacer push de nuevos commits.

Pruebas de webhooks de GitHub vs smee.io

smee.io es un proxy de webhooks de GitHub popular para el desarrollo local. Funciona bien para el reenvío básico pero carece de inspección de peticiones y replay integrados. PortPreview combina túnel con captura y replay en una sola herramienta. Para una guía más amplia de depuración de webhooks, mira cómo depurar webhooks en local.

Únete a la lista de espera de PortPreview para pruebas de webhooks de GitHub con visibilidad de peticiones integrada.