Webhooks de GitLab: configuración, verificación y fallos
Webhooks de GitLab
Webhooks de GitLab: configuración, signing token y desactivación | We.Inc
Añade un webhook de proyecto o grupo en GitLab, elige los eventos, verifica la cabecera webhook-signature o X-Gitlab-Token y descubre cuándo GitLab desactiva un hook que falla.
Un webhook de GitLab envía un HTTP POST a tu URL cuando ocurre un evento en un proyecto o grupo, como un push, una merge request o un comentario nuevo. Se añade en Configuración, Webhooks. Protégelo con un signing token y responde rápido con 200, porque GitLab desactiva los hooks que fallan de forma reiterada.
Datos de los webhooks de GitLab (docs.gitlab.com, octubre de 2026)
Elemento
Lo que documenta GitLab
Quién puede añadir un hook de proyecto
Rol Maintainer u Owner
Webhooks de grupo
Planes Premium y Ultimate
Desactivación temporal
Tras 4 fallos consecutivos, empezando por 1 minuto y creciendo hasta 24 horas
Desactivación permanente
Tras 40 fallos consecutivos
Tiempo de espera en GitLab.com
10 segundos
Hooks por proyecto / grupo en GitLab.com
Eventos recientes guardados
Peticiones de los últimos dos días
Los webhooks son la forma en que GitLab avisa a tu sitio, tu script de despliegue o el chat de tu equipo de que algo ha cambiado, sin que tu código tenga que preguntar una y otra vez. La configuración lleva un minuto; lo que da problemas después es demostrar que una petición viene de GitLab y evitar que el hook se desactive. El comprobador de abajo genera una firma con signing token en tu navegador para que puedas probar tu receptor.
Abre el proyecto y, en la barra lateral izquierda, elige Configuración, Webhooks y selecciona Añadir nuevo webhook.
Introduce el endpoint en URL, codificando con porcentaje los caracteres especiales, y añade un Nombre y una Descripción si quieres.
Selecciona Generar signing token y cópialo enseguida; GitLab solo lo muestra una vez.
En Disparador, marca los eventos que quieras, como eventos de push o de merge request, y selecciona Añadir webhook.
Usa la opción Probar para enviar una entrega de ejemplo y luego abre Editar y Eventos recientes para ver la petición y la respuesta de tu servidor.
Responde con 200 o 201 en cuanto llegue la petición y haz el trabajo real en segundo plano. Los tiempos de espera agotados cuentan como fallos.
Devuelve 4xx solo cuando el propio hook esté mal configurado. GitLab cuenta cada respuesta 4xx o 5xx como un fallo de cara a desactivarlo.
Usa la cabecera webhook-id o Idempotency-Key, que no cambian entre reintentos, para ignorar un reintento que ya has procesado.
Rechaza las entregas cuyo webhook-timestamp sea antiguo, para que una petición capturada no pueda reenviarse más tarde.
Si un hook se desactivó de forma permanente, arregla primero el receptor y después envía una petición de prueba que reciba una respuesta 2xx para volver a activarlo.
Preguntas frecuentes
¿Qué es X-Gitlab-Token?
Es el antiguo token secreto. Si defines uno, GitLab lo envía como texto plano en la cabecera X-Gitlab-Token y tu servidor lo compara. La documentación de GitLab recomienda ahora un signing token para los webhooks nuevos.
¿Por qué se desactivó mi webhook de GitLab?
GitLab desactiva un hook tras cuatro fallos consecutivos, es decir, respuestas 4xx o 5xx, tiempos de espera de conexión agotados u otros errores HTTP. Primero queda desactivado un minuto, más tiempo con cada nuevo fallo hasta 24 horas, y de forma permanente tras 40 seguidos.
¿Cómo sé qué evento ha llegado?
Lee la cabecera X-Gitlab-Event. Su valor es el tipo de evento seguido de Hook, por ejemplo Push Hook, Merge Request Hook, Note Hook para comentarios o Pipeline Hook.
¿Puedo añadir un webhook a todo un grupo?
Sí, en los planes Premium y Ultimate. Un webhook de grupo se dispara con eventos de todos los proyectos del grupo y también puede recibir eventos de miembros del grupo, proyectos y subgrupos.
¿Funciona el signing token en GitLab autogestionado?
La documentación de GitLab indica que llegó en la versión 19.0 tras un feature flag activado por defecto y pasó a estar disponible de forma general en la 19.1. Las versiones autogestionadas anteriores solo tienen el token secreto.
Cómo funciona el signing token
Un signing token empieza por whsec_. Quita ese prefijo y decodifica el resto en base64 para obtener la clave. GitLab firma la cadena formada por el webhook-id, un punto, el webhook-timestamp, un punto y el cuerpo sin procesar, usando HMAC-SHA256.
El resultado se codifica en base64 y se envía en la cabecera webhook-signature como v1, seguido de la firma. GitLab sigue la especificación Standard Webhooks, así que las bibliotecas escritas para ese formato también pueden verificarla.
Pasar de un token secreto sin interrupciones
Un hook puede llevar los dos tokens a la vez. Configura el signing token, cambia tu receptor para que compruebe la firma cuando esté presente y recurra a X-Gitlab-Token cuando no, y después elimina el secreto antiguo.
Este receptor comprueba la firma del signing token, rechaza marcas de tiempo caducadas y recurre al token secreto antiguo mientras migras.
Los tokens vienen de variables de entorno. La ventana de validez de cinco minutos es elección nuestra; elige la que te convenga.
Eventos habituales y sus valores de X-Gitlab-Event
Eventos de webhook de GitLab
Evento
Cabecera X-Gitlab-Event
Push
Push Hook
Push de etiqueta
Tag Push Hook
Incidencia o elemento de trabajo
Issue Hook
Comentario
Note Hook
Merge request
Merge Request Hook
Pipeline
Pipeline Hook
Job
Job Hook
Despliegue
Deployment Hook
Release
Release Hook
Página de wiki
Wiki Page Hook
Generador de firmas con signing token
Introduce un signing token, el webhook-id, el webhook-timestamp y el cuerpo sin procesar para obtener el valor de webhook-signature que enviaría GitLab. Todo se ejecuta en tu navegador.
Signing token (empieza por whsec_)
Cuerpo de la petición sin procesar
El token debe empezar por whsec_ seguido de texto en base64.
El token precargado es un ejemplo inventado, no una clave real. Con estos valores el resultado es:
¿Cuándo desactiva GitLab un hook?
Entregas fallidas consecutivas: {n}
Activo: las entregas continúan.
Desactivado temporalmente: primero 1 minuto, más tiempo con cada nuevo fallo, hasta 24 horas, y luego se reactiva automáticamente.
Desactivado permanentemente: sigue así hasta que una petición de prueba reciba una respuesta 2xx.