Como Usar Webhooks do Discord para Notificações de Pipeline no GitLab

Você quer que o GitLab envie atualizações de status de pipeline diretamente em um canal do Discord. Webhooks permitem que o GitLab envie mensagens automaticamente para o Discord quando um pipeline é bem-sucedido, falha ou é bloqueado. Este artigo explica como criar uma URL de webhook do Discord, configurar o GitLab para usá-la e personalizar o formato da notificação.

O que os Webhooks do Discord Fazem para Pipelines do GitLab

Um webhook do Discord é um endpoint HTTP simples que aceita dados JSON e os publica como uma mensagem em um canal específico. O GitLab envia uma requisição POST para esse endpoint toda vez que um evento de pipeline ocorre — por exemplo, quando um pipeline inicia, é bem-sucedido, falha ou é cancelado.

A integração com webhook não requer bot ou código personalizado. Você só precisa de uma URL de webhook do Discord e das configurações de webhook do projeto GitLab. O GitLab envia um payload padrão, mas você pode substituí-lo por uma mensagem personalizada usando o formato de webhook do Discord.

Antes de começar, confirme que você tem o seguinte:

• Permissão Gerenciar Webhooks no servidor do Discord (ou peça a um administrador do servidor para criar o webhook)
• Pelo menos a função Maintainer no projeto GitLab
• Pipeline do GitLab já configurado e em execução

Passos para Configurar um Webhook do Discord para Notificações de Pipeline do GitLab

Siga estes passos para conectar o GitLab ao Discord. O processo tem duas partes: criar o webhook no Discord e adicioná-lo ao GitLab.

Criar um Webhook no Discord

1. Abra as Configurações do Servidor
   Clique com o botão direito no nome do servidor do Discord na lista de canais e selecione Configurações do Servidor. Se você não vir esta opção, não tem a permissão Gerenciar Servidor.
2. Vá para Integrações
   Na barra lateral esquerda, clique em Integrações. Em seguida, clique na aba Webhooks se não estiver selecionada.
3. Crie um novo webhook
   Clique no botão Criar Webhook. Uma nova entrada de webhook aparece.
4. Nomeie o webhook e selecione um canal
   Dê ao webhook um nome como “Notificações de Pipeline do GitLab.” Escolha o canal do Discord onde você quer que as mensagens apareçam. Você também pode alterar o avatar clicando no ícone padrão.
5. Copie a URL do webhook
   Clique no botão Copiar URL do Webhook. Armazene esta URL com segurança — qualquer pessoa com esta URL pode postar mensagens no canal selecionado.
6. Salve as alterações
   Clique em Salvar para confirmar o webhook.

Adicionar o Webhook ao GitLab

1. Abra as configurações do projeto GitLab
   Vá para o seu projeto GitLab e navegue até Configurações > Webhooks na barra lateral esquerda.
2. Cole a URL do webhook do Discord
   No campo URL, cole a URL do webhook que você copiou do Discord.
3. Defina os eventos de gatilho
   Em Gatilho, marque pelo menos os seguintes eventos:
   – Eventos de pipeline
   – Eventos de job (opcional, para notificações por job)
4. Ative a verificação SSL
   Deixe a opção Ativar verificação SSL marcada. O Discord exige conexões HTTPS.
5. Adicione um nome de webhook personalizado (opcional)
   No campo Descrição, digite um rótulo como “Alertas de pipeline no Discord” para sua própria referência.
6. Teste o webhook
   Clique no botão Testar e selecione Eventos de push ou Eventos de pipeline. O GitLab envia um payload de teste para o Discord. Se o teste falhar, verifique se a URL está correta e se o canal ainda existe.
7. Salve o webhook
   Clique em Adicionar webhook. O webhook aparece na lista com uma marca de verificação verde se estiver ativo.

Personalizando a Mensagem de Notificação

O GitLab envia um payload JSON padrão que o Discord interpreta como uma mensagem de texto simples. Para exibir embeds ricos com status do pipeline, detalhes do commit e nomes de branch, você deve criar um payload personalizado usando o formato de webhook do Discord.

O GitLab permite substituir o payload por um corpo JSON personalizado. Vá para Configurações > Webhooks, clique em Editar no seu webhook e expanda a seção Modelo de webhook personalizado. Cole um objeto JSON que siga a estrutura de embed do Discord.

Aqui está um exemplo de payload personalizado para uma notificação de pipeline:

{
  "embeds": [{
    "title": "Pipeline #{object_attributes.id}",
    "url": "${object_attributes.url}",
    "color": "${object_attributes.status == 'success' ? 3066993 : 15158332}",
    "fields": [
      {"name": "Projeto", "value": "${project.path_with_namespace}", "inline": true},
      {"name": "Branch", "value": "${object_attributes.ref}", "inline": true},
      {"name": "Status", "value": "${object_attributes.status}", "inline": true},
      {"name": "Commit", "value": "${commit.message}"}
    ],
    "timestamp": "${object_attributes.created_at}"
  }]
}

As variáveis dentro de ${} são placeholders do GitLab que são substituídos por dados reais em tempo de execução. Você pode usar qualquer variável do payload do webhook do GitLab — a lista completa está na documentação de eventos de webhook do GitLab.

Para testar seu payload personalizado, clique no botão Testar e selecione Eventos de pipeline. Verifique o canal do Discord para ver se o embed aparece corretamente. Ajuste a sintaxe JSON se a mensagem estiver vazia ou mostrar texto bruto.

Problemas Comuns e Como Evitá-los

Teste do Webhook é Bem-sucedido, mas Eventos de Pipeline Não São Enviados

Se o teste manual funciona, mas eventos reais de pipeline não disparam, a URL do webhook pode estar correta, mas os eventos de pipeline não estão sendo gerados. Verifique se o pipeline CI/CD do GitLab realmente está sendo executado. Também confira se você selecionou Eventos de pipeline em Gatilho, não apenas Eventos de push. Vá para Configurações > Webhooks, clique em Editar no seu webhook e confirme as caixas de seleção.

Discord Exibe JSON Bruto em Vez de um Embed

Isso acontece quando o payload personalizado é JSON inválido ou não segue a estrutura de embed do Discord. Use um validador JSON para verificar a sintaxe. Erros comuns incluem vírgulas faltando, aspas duplas dentro do JSON ou uso de aspas simples em vez de duplas. Copie o exemplo de payload acima e substitua apenas os placeholders de variáveis.

URL do Webhook Muda Após Modificações nas Configurações do Servidor

As URLs de webhook do Discord permanecem estáveis a menos que o webhook seja excluído ou o proprietário do servidor regenere a URL. Se você excluir e recriar um webhook, deve atualizar a URL no GitLab. Para evitar tempo de inatividade, mantenha o webhook antigo ativo enquanto testa um novo e remova o webhook antigo após confirmar que o novo funciona.

Webhook do Discord vs Notificações Nativas do GitLab

Recurso	Webhook do Discord	Notificação por Email do GitLab
Complexidade de configuração	Requer URL de webhook e configuração de webhook no GitLab	Integrado ao GitLab, usa preferências de email do usuário
Formato da mensagem	Embeds ricos com campos personalizados, cores e menções	Email em texto simples
Velocidade de entrega	Quase em tempo real	Depende da latência do servidor de email
Direcionamento de canal	Publica em um único canal do Discord por webhook	Entregue em caixas de entrada de email individuais
Personalização	Controle total via payload JSON	Limitado aos modelos de notificação do GitLab

Agora você pode enviar atualizações de status de pipeline do GitLab para qualquer canal do Discord usando webhooks. Comece criando um webhook no Discord, depois configure-o no GitLab em Configurações > Webhooks. Para notificações mais ricas, substitua o payload padrão por um embed JSON personalizado que mostre ID do pipeline, branch, status e detalhes do commit. Como passo avançado, use variáveis CI/CD do GitLab para definir dinamicamente a URL do webhook para diferentes ambientes, como staging e produção.