GitScrum / Docs

Solución de Problemas

Diagnostica y corrige problemas comunes de webhooks de GitScrum: fallos de entrega, errores de timeout, problemas de payload y errores de configuración.

Problemas comunes de webhook y cómo resolverlos.

El Webhook No Dispara

Endpoint no guardado

Síntoma: Ninguna solicitud llega a tu servidor después de configurar un webhook.

Solución:

  1. Verifica que el indicador de estado esté verde en la configuración del webhook
  2. Reingresa la URL y presiona Enter para guardar
  3. Actualiza la página y confirma que la URL persiste

Proyecto incorrecto

Síntoma: Los webhooks funcionan para un proyecto, pero no para otro.

Solución: Los webhooks son por proyecto. Verifica que hayas configurado el endpoint en la configuración del proyecto correcto.

Plan Pro necesario

Síntoma: La configuración de webhook aparece, pero los endpoints no se activan.

Solución: Los webhooks requieren un plan Pro o superior. Verifica el estado de facturación de tu workspace.

Fallos de Entrega

El endpoint devuelve estado no-2xx

Síntoma: GitScrum muestra fallo de entrega para un webhook.

Solución:

  • Verifica los logs de tu servidor para errores
  • Asegúrate de que tu endpoint devuelva un código de estado 2xx (200, 201, 202, 204)
  • Verifica que la ruta del endpoint coincida exactamente

Timeout de conexión

Síntoma: Las entregas de webhook fallan consistentemente con errores de timeout.

Solución:

  • Devuelve 200 inmediatamente antes de procesar (usa procesamiento basado en cola)
  • Verifica que tu servidor responda dentro de 30 segundos
  • Comprueba que tu servidor no esté bloqueado por un firewall

Errores SSL/TLS

Síntoma: Las entregas de webhook HTTPS fallan.

Solución:

  • Asegúrate de que tu certificado SSL sea válido y no haya expirado
  • Verifica que la cadena de certificados esté completa
  • Confirma que tu servidor soporte TLS 1.2 o superior

Problemas de Payload

Payload vacío o malformado

Síntoma: Tu endpoint recibe la solicitud, pero el cuerpo está vacío o no se puede parsear.

Solución:

  • Asegúrate de que tu servidor parsee el content type application/json
  • Agrega el middleware express.json() (Node.js) o equivalente
  • Verifica que tu biblioteca de parsing soporte el tamaño del payload
// Express.js - ensure JSON parsing is enabled
app.use(express.json({ limit: '10mb' }));
# Flask - ensure JSON content type is handled
event = request.get_json(force=True)

Estructura de payload inesperada

Síntoma: Tu código falla porque campos esperados están ausentes.

Solución:

  • Siempre verifica valores null antes de acceder a propiedades anidadas
  • Usa optional chaining en JavaScript: data?.workflow?.title
  • Valida la estructura del payload antes de procesar
  • Consulta Formato del Payload para la referencia completa de campos

Problemas de Prueba

El botón de prueba envía, pero el servidor no recibe

Síntoma: Hacer clic en el botón de prueba muestra éxito, pero ninguna solicitud llega a tu servidor.

Solución:

  • Verifica que tu servidor sea accesible públicamente (no esté detrás de VPN o red local)
  • Confirma que la URL sea correcta incluyendo el protocolo (https://)
  • Intenta usar una herramienta de inspección de solicitudes como webhook.site para verificar la entrega
  • Si usas ngrok, asegúrate de que el túnel siga activo

La prueba funciona, pero los eventos reales no disparan

Síntoma: Los payloads de prueba llegan, pero los eventos reales no activan webhooks.

Solución:

  • Verifica que el evento específico esté configurado (la prueba envía al endpoint específico)
  • Confirma que la acción que realizas corresponda al tipo de evento
  • Asegúrate de que estés realizando la acción en el proyecto correcto

Problemas de Permisos

No puedes acceder a la configuración de webhooks

Síntoma: La pestaña Webhooks no es visible o la configuración es de solo lectura.

Solución:

  • Solo los roles Manager y Owner pueden configurar webhooks
  • Contacta al gerente del proyecto o al owner del workspace para acceso

Consejos de Depuración

Usa webhook.site para inspección

Prueba tu configuración de webhook usando webhook.site:

  1. Ve a webhook.site y copia la URL única
  2. Pégala como endpoint en los webhooks de GitScrum
  3. Dispara un evento o haz clic en Test
  4. Inspecciona los detalles completos de la solicitud en webhook.site

Verifica los logs de entrega

GitScrum registra cada intento de entrega de webhook incluyendo:

  • URL del endpoint
  • Cuerpo del payload
  • Código de estado HTTP devuelto
  • Marca de tiempo

Revisa estos logs para diagnosticar problemas de entrega.

Desarrollo local con ngrok

Para pruebas locales, usa ngrok para crear un túnel público:

ngrok http 3000

La URL HTTPS proporcionada por ngrok se puede usar como URL del endpoint de webhook. Reemplázala en GitScrum cuando la URL del túnel cambie.

Relacionado