¿Tu canal de Microsoft Teams ha dejado de recibir alertas de tu pipeline CI/CD en GitLab? Este artículo describe por qué un incoming webhook puede dejar de funcionar de la noche a la mañana y cómo restaurarlo paso a paso sin perder visibilidad sobre tus despliegues.

Resumen del problema

Un webhook configurado como Incoming Webhook dejó de entregar mensajes en un canal de Microsoft Teams aunque el pipeline de GitLab continúa ejecutándose con normalidad. El fallo se presenta sin errores visibles en la interfaz de Teams y sin cambios aparentes en el código del pipeline.

Diagnóstico rápido

Paso	Qué verificar / hacer	Por qué ayuda
Comprobar estado del servicio	Visita el portal de estado de Microsoft 365 para descartar incidentes globales o regionales que afecten a los conectores.	Un corte a nivel de plataforma puede bloquear todos los webhooks sin que tu configuración cambie.
Validar el permiso de canal	En la configuración del equipo o canal, confirma que la opción “Allow connectors to submit channel messages” siga habilitada.	Si el permiso se deshabilita, cualquier webhook existente dejará de funcionar hasta que se reactive.
Probar la URL del webhook	Envía manualmente un POST con curl o Postman y comprueba que la respuesta sea 200 OK.	Distingue errores de Teams frente a problemas en tu código o pipeline.
Regenerar o crear un nuevo webhook	Desvincula el conector actual, genera una nueva URL y actualízala en el script de GitLab.	Las URLs pueden invalidarse si se cambian políticas del inquilino o se elimina el conector.
Revisar cambios de seguridad / políticas	Pide al administrador que verifique Microsoft Purview y el Centro de seguridad por cambios en políticas que afecten a bots o conectores.	Los controles de la organización pueden bloquear mensajes de bots o webhooks sin aviso previo.
Auditar logs del pipeline	Registra la respuesta HTTP de Teams y activa la opción fail on non‑200 en tu script de notificación.	Obtendrás información inmediata si el error reaparece y acelerarás la resolución.

Paso a paso detallado

Comprobar estado del servicio de Microsoft 365

Abre el portal de administración de Microsoft 365 con una cuenta de administrador global. En la sección Health → Service health revisa si existen incidentes activos relacionados con Microsoft Teams o específicamente con “Connectors”. Si encuentras un aviso, documenta el Service ID y la hora de inicio; te ayudará a justificar la interrupción y evitarás invertir tiempo en investigar un problema que está fuera de tu control.

Validar el permiso de canal

1. Ve al canal afectado y abre Manage channel.
2. En Connectors, verifica que “Allow connectors to submit channel messages” esté activado.
3. Si la opción aparece deshabilitada, habilítala y guarda los cambios. Vuelve a probar el pipeline.

Si tu organización aplica políticas restrictivas, el conector puede haberse deshabilitado al actualizarse un policy package. Conviene mantener una checklist de cambios de políticas para correlacionar incidentes en el futuro.

Probar la URL del webhook

Antes de culpar a GitLab, asegúrate de que la URL continúa viva y acepta peticiones:

curl -X POST -H "Content-Type: application/json" \
     -d '{"text":"Prueba de conectividad al webhook"}' \
     "https://.webhook.office.com/webhookb2/@/IncomingWebhook//" -i

Interpreta la respuesta:

• 200 OK: El mensaje llegó a Teams; el problema está en el pipeline.
• 403 Forbidden: El conector existe, pero una política bloquea su uso.
• 404 Not Found o 410 Gone: La URL es inválida; crea un nuevo webhook.
• 429 Too Many Requests: Estás superando los límites de velocidad; añade retardo exponencial.

Regenerar o crear un nuevo webhook

Si recibes 404, 410 o sospechas que la URL se ha filtrado, elimina el conector y créalo desde cero:

1. En el canal, selecciona Connectors → Incoming Webhook → Configure.
2. Asigna un nombre, icónico, por ejemplo, “GitLab CI Production”.
3. Copia la URL y substitúyela en la variable protegida del pipeline ($TEAMSWEBHOOKURL).
4. Lanza un pipeline manual para verificar la entrega.

Este paso restablece tokens internos y fuerza nuevos certificados válidos en la cadena TLS.

Revisar cambios de seguridad o políticas

Los administradores suelen endurecer las políticas sin avisar. Accede al Centro de administración de Teams:

1. En Teams apps → Manage apps, busca Incoming Webhook. Confirma que el estado sea “Allowed”.
2. En Org‑wide app settings verifica que External apps esté habilitado para webhooks.
3. Consulta Microsoft Purview → Audit para ver cuándo se modificó la política y qué administrador lo hizo.

Si tu organización exige seguimiento, crea un ticket formal para revertir o justificar el cambio.

Auditar logs del pipeline de GitLab

Para evitar que estos fallos pasen inadvertidos:

• En el script de notificación añade: set -euo pipefail y finaliza el job si la respuesta no es 200.
• Guarda la salida de curl -i en un artefacto de GitLab. Así dispondrás del cuerpo y cabeceras para análisis.
• Implementa retry con retardo exponencial; Microsoft Teams impone límites de 4 peticiones por segundo y 1 000 por hora por webhook.

Errores HTTP más comunes y cómo solucionarlos

Código	Significado habitual	Acción recomendada
200 OK	Mensaje aceptado.	No requiere acción.
400 Bad Request	JSON mal formado.	Valida la carga; recuerda que los arrays anidados no están soportados.
403 Forbidden	Política o permiso bloquea el webhook.	Revisa configuraciones de canal y políticas.
404 Not Found	URL eliminada.	Genera un nuevo webhook y actualiza la variable en GitLab.
410 Gone	Recurso purgado por retención de datos.	Regenera el webhook; considera reducir la rotación de conectores.
429 Too Many Requests	Límite de velocidad superado.	Añade back‑off e implementa colas.
500/502	Error temporal en Teams.	Reintenta con exponencial (1s, 2s, 4s, 8s).

Lecciones aprendidas y buenas prácticas

• Visibilidad inmediata: Los errores silenciosos son los más costosos. Configura alertas en GitLab para fallos de notificación.
• Gestión de secretos: Almacena la URL en un Secret Variable protegida; evita exponerla en repositorios o echo del job.
• Control de cambios: Registra cuándo se actualiza el webhook y quién lo hace. GitLab protected variables ayuda a auditar.
• Documentación viva: Añade al README del proyecto un apartado para restablecer webhooks. Facilita la rotación de personal.
• Automatiza pruebas periódicas: Un pequeño job programado cada hora que envíe “ping” al webhook y alerte por correo si falla te evitará sorpresas.

Automatizar la supervisión de un webhook

Ejemplo de job en .gitlab-ci.yml que verifica el webhook sin recurrir al pipeline principal:

webhook_healthcheck:
  stage: monitoring
  script:
    - |
      RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
        -H "Content-Type: application/json" \
        -d '{"text":"🩺 Health check Teams Webhook"}' \
        "$TEAMSWEBHOOKURL")
      if [ "$RESPONSE" != "200" ]; then
        echo "Webhook devolvió $RESPONSE"
        exit 1
      fi
  only:
    - schedules

Así recibirás un fallo explícito en GitLab si la integración se rompe, incluso cuando no haya despliegues activos.

Preguntas frecuentes

¿Puedo usar la misma URL de webhook en varios proyectos?

Sí, pero aumenta el riesgo: un proyecto podría inundar el canal y provocar bloqueo por límite de velocidad. Si los equipos son distintos, usa un webhook por proyecto.

¿Cuánto dura una URL de webhook?

No expira por tiempo, pero se invalida si: se elimina el conector, el canal, el equipo, el inquilino o si una política de retención purga la instancia.

¿Los webhooks soportan tarjetas adaptativas?

El Incoming Webhook clásico admite tarjetas adaptativas (JSON Adaptive Card 1.2). Revisa que el JSON sea válido y no incluya $schema para evitar Bad Request.

Conclusión

La mayoría de los cortes en webhooks de Microsoft Teams se reducen a permisos de canal o políticas de organización. Con la rutina de diagnóstico descrita —estado del servicio, permisos, prueba directa y regeneración— puedes restaurar la funcionalidad en minutos y añadir salvaguardas para que tu pipeline nunca vuelva a quedar mudo.