Webhooks do GitLab: configuração, verificação e falhas
Webhooks do GitLab
Webhooks do GitLab: configuração, signing token e desativação | We.Inc
Adicione um webhook de projeto ou de grupo no GitLab, escolha os gatilhos, verifique o cabeçalho webhook-signature ou o X-Gitlab-Token e veja quando o GitLab desativa um hook que falha.
Um webhook do GitLab envia um HTTP POST para a sua URL quando algo acontece em um projeto ou grupo, como um push, um merge request ou um novo comentário. Adicione um em Settings, Webhooks. Proteja-o com um signing token e responda rápido com 200, porque o GitLab desativa hooks que continuam falhando.
Fatos sobre webhooks do GitLab (docs.gitlab.com, outubro de 2026)
Item
O que o GitLab documenta
Quem pode adicionar um hook de projeto
Papel Maintainer ou Owner
Webhooks de grupo
Planos Premium e Ultimate
Desativação temporária
Depois de 4 falhas seguidas, começando com 1 minuto e aumentando até 24 horas
Desativação permanente
Depois de 40 falhas seguidas
Timeout no GitLab.com
10 segundos
Hooks por projeto / grupo no GitLab.com
Eventos recentes guardados
Requisições dos últimos dois dias
Webhooks são a forma de o GitLab avisar o seu site, script de deploy ou chat da equipe de que algo mudou, sem que o seu código precise perguntar de novo e de novo. A configuração leva um minuto; o que dá trabalho depois é provar que uma requisição veio do GitLab e evitar que o hook seja desligado. O verificador abaixo monta uma assinatura de signing token no seu navegador para você testar o seu receptor.
Abra o projeto e, na barra lateral esquerda, escolha Settings, Webhooks e selecione Add new webhook.
Informe o endpoint em URL, aplicando percent-encoding a caracteres especiais, e adicione um Name e uma Description se quiser.
Selecione Generate signing token e copie o token na hora; o GitLab mostra ele uma única vez.
Em Trigger, marque os eventos que deseja, como push events ou merge request events, e selecione Add webhook.
Use a opção Test para enviar uma entrega de exemplo e depois abra Edit e Recent events para ver a requisição e a resposta do seu servidor.
Responda com 200 ou 201 assim que a requisição chegar e faça o trabalho de verdade em segundo plano. Timeouts contam como falhas.
Retorne 4xx só quando o próprio hook estiver mal configurado. O GitLab trata toda resposta 4xx ou 5xx como uma falha rumo à desativação.
Use o cabeçalho webhook-id ou Idempotency-Key, que não mudam entre novas tentativas, para ignorar uma repetição que você já processou.
Rejeite entregas cujo webhook-timestamp seja antigo, para que uma requisição capturada não possa ser reenviada depois.
Se um hook foi desativado de forma permanente, corrija primeiro o receptor e depois envie uma requisição de teste que receba resposta 2xx para reativá-lo.
Perguntas frequentes
O que é o X-Gitlab-Token?
É o secret token mais antigo. Quando você define um, o GitLab o envia como texto puro no cabeçalho X-Gitlab-Token e o seu servidor faz a comparação. A documentação do GitLab agora recomenda um signing token para webhooks novos.
Por que o meu webhook do GitLab foi desativado?
O GitLab desativa um hook depois de quatro falhas seguidas, ou seja, respostas 4xx ou 5xx, timeouts de conexão ou outros erros HTTP. Primeiro ele fica desligado por um minuto, por mais tempo a cada nova falha até 24 horas, e de forma permanente depois de 40 seguidas.
Como sei qual evento chegou?
Leia o cabeçalho X-Gitlab-Event. O valor é o tipo de evento seguido de Hook, por exemplo Push Hook, Merge Request Hook, Note Hook para comentários ou Pipeline Hook.
Posso adicionar um webhook a um grupo inteiro?
Sim, nos planos Premium e Ultimate. Um webhook de grupo dispara para eventos de todos os projetos do grupo e também pode receber eventos de membros do grupo, de projetos e de subgrupos.
O signing token funciona no GitLab self-managed?
A documentação do GitLab diz que ele chegou na versão 19.0 atrás de uma feature flag ativada por padrão e ficou disponível para todos na 19.1. Versões self-managed mais antigas só têm o secret token.
Como o signing token funciona
Um signing token começa com whsec_. Tire esse prefixo e decodifique o resto em base64 para obter a chave. O GitLab assina a string formada pelo webhook-id, um ponto, o webhook-timestamp, um ponto e o corpo bruto, usando HMAC-SHA256.
O resultado é codificado em base64 e enviado no cabeçalho webhook-signature como v1, seguido da assinatura. O GitLab segue a especificação Standard Webhooks, então bibliotecas escritas para esse formato também conseguem verificá-la.
Migrando de um secret token sem interrupção
Um hook pode ter os dois tokens ao mesmo tempo. Configure o signing token, mude o seu receptor para verificar a assinatura quando ela existir e recorrer ao X-Gitlab-Token quando não existir, e depois remova o secret antigo.
Este receptor verifica a assinatura do signing token, rejeita timestamps antigos e recorre ao secret token antigo enquanto você migra.
Os tokens vêm de variáveis de ambiente. A janela de validade de cinco minutos é escolha nossa; use o que fizer sentido para você.
Eventos comuns e os seus valores de X-Gitlab-Event
Eventos de webhook do GitLab
Evento
Cabeçalho X-Gitlab-Event
Push
Push Hook
Push de tag
Tag Push Hook
Issue ou item de trabalho
Issue Hook
Comentário
Note Hook
Merge request
Merge Request Hook
Pipeline
Pipeline Hook
Job
Job Hook
Deploy
Deployment Hook
Release
Release Hook
Página de wiki
Wiki Page Hook
Gerador de assinatura do signing token
Informe um signing token, o webhook-id, o webhook-timestamp e o corpo bruto para obter o valor de webhook-signature que o GitLab enviaria. Tudo roda no seu navegador.
Signing token (começa com whsec_)
Corpo bruto da requisição
O token precisa começar com whsec_ seguido de texto em base64.
O token preenchido é um exemplo inventado, não uma chave real. Com esses valores, o resultado é:
Quando o GitLab desativa um hook?
Entregas com falha seguidas: {n}
Ativo: as entregas continuam.
Desativado temporariamente: desligado por 1 minuto no início, por mais tempo a cada nova falha, até 24 horas, e depois reativado automaticamente.
Desativado permanentemente: fica desligado até que uma requisição de teste receba resposta 2xx.