Como Usar Webhook do Discord com GitHub Actions para Notificações de Deploy

Você quer enviar uma notificação para seu servidor Discord sempre que um workflow do GitHub Actions concluir um deploy. Um webhook é um callback HTTP simples que publica uma mensagem em um canal do Discord automaticamente. Usar um webhook do Discord com GitHub Actions elimina a necessidade de verificar manualmente a aba GitHub Actions. Este artigo explica como criar um webhook do Discord, configurar um segredo no GitHub Actions e escrever uma etapa do workflow que envia uma notificação de deploy.

O Que é um Webhook do Discord e Como Funciona com GitHub Actions

Um webhook do Discord é uma ferramenta que permite que serviços externos enviem mensagens para um canal do Discord. Quando você cria um webhook em um canal do Discord, o Discord gera uma URL única. Qualquer aplicação que enviar uma requisição HTTP POST para essa URL com um payload JSON formatado corretamente fará com que o Discord exiba uma mensagem naquele canal. O GitHub Actions pode enviar essas requisições POST usando o comando curl ou uma ação dedicada do GitHub. A URL do webhook é sensível porque qualquer pessoa que a tenha pode publicar no seu canal. Por isso, você armazena a URL como um segredo do GitHub Actions.

Antes de começar, você precisa de três coisas: um servidor Discord onde você tenha permissão para Gerenciar Webhooks, um repositório GitHub com pelo menos um arquivo de workflow e um terminal ou navegador para copiar a URL do webhook. Você não precisa de um token de bot ou de qualquer aplicação Discord adicional. O sistema de webhook está integrado diretamente nas configurações do canal do Discord.

Como o Payload da Mensagem Funciona

O payload JSON que você envia para a URL do webhook determina a aparência da mensagem. Você pode incluir uma mensagem de texto simples ou um embed rico com título, descrição, barra colorida, campos e um timestamp. Para notificações de deploy, um embed é a escolha padrão porque mostra o nome do workflow, a mensagem do commit, o autor e o status em um layout limpo de cartão. O comando curl no seu workflow do GitHub Actions construirá esse JSON e o enviará com o cabeçalho Content-Type: application/json.

Passos para Configurar um Webhook do Discord para Notificações de Deploy com GitHub Actions

Siga estes passos para criar o webhook, armazenar a URL e adicionar uma etapa de notificação ao seu workflow de deploy.

1. Crie um Webhook do Discord no Seu Servidor
   Abra o Discord e vá para o servidor onde você quer as notificações. Clique com o botão direito no nome do canal e selecione Editar Canal. Vá em Integrações, depois clique em Webhooks. Clique em Criar Webhook. Dê um nome, como Deploy Bot, e opcionalmente altere o avatar. Clique em Copiar URL do Webhook. Salve esta URL temporariamente. Clique em Salvar Alterações.
2. Adicione a URL do Webhook como um Segredo do GitHub Actions
   Vá para o seu repositório GitHub. Clique em Settings > Secrets and variables > Actions. Clique em New repository secret. Defina o nome como DISCORD_WEBHOOK. Cole a URL do webhook no campo Secret. Clique em Add secret. A URL agora está criptografada e disponível para seus workflows como ${{ secrets.DISCORD_WEBHOOK }}.
3. Crie ou Edite Seu Arquivo de Workflow de Deploy
   No seu repositório, navegue até .github/workflows/ e abra o arquivo YAML do seu workflow de deploy. Se você não tiver um, crie um arquivo como deploy.yml. O arquivo já deve conter etapas para construir e implantar sua aplicação.
4. Adicione uma Etapa de Notificação Após a Etapa de Deploy
   Adicione uma nova etapa ao final do workflow. Use o comando curl para enviar uma requisição POST para a URL do webhook. A etapa deve ser executada apenas quando o deploy for bem-sucedido. Use a condição if: success(). Abaixo está um exemplo de etapa que envia um embed simples:

   - name: Enviar notificação Discord
     if: success()
     env:
       DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
     run: |
       curl -H "Content-Type: application/json" \
       -X POST \
       -d '{
         "embeds": [{
           "title": "Deploy bem-sucedido",
           "description": "O commit mais recente foi implantado.",
           "color": 3066993,
           "fields": [
             {"name": "Repositório", "value": "${{ github.repository }}", "inline": true},
             {"name": "Branch", "value": "${{ github.ref_name }}", "inline": true},
             {"name": "Commit", "value": "${{ github.sha }}", "inline": false}
           ],
           "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
         }]
       }' "$DISCORD_WEBHOOK"

   O valor color 3066993 é verde. Para uma notificação de falha, use 15158332 vermelho.

5. Teste o Workflow
   Faça um push de um commit para o branch que aciona seu workflow de deploy. Vá para a aba Actions no GitHub e observe o workflow ser executado. Após a etapa de deploy ser concluída, verifique o canal do Discord. Você deve ver a mensagem embed aparecer em segundos. Se a mensagem não aparecer, verifique o nome do segredo da URL do webhook e a condição da etapa.

Erros Comuns e Limitações

URL do Webhook Inválida ou Ausente

Se a mensagem do Discord nunca aparecer, a URL do webhook pode estar errada ou o nome do segredo pode estar com erro de digitação. Confirme se o nome do segredo no GitHub corresponde exatamente ao que você usa no workflow. Além disso, verifique se o webhook foi salvo no Discord após copiar a URL. Você pode testar o webhook enviando um comando curl do seu terminal local com a URL bruta.

Etapa do Workflow Executa, mas Nenhuma Mensagem Aparece

O workflow pode ter executado a etapa, mas o payload JSON estava mal formatado. Verifique os logs de execução do workflow para a etapa curl. Se a resposta for 204 No Content, a requisição foi aceita. Um erro 400 significa que a estrutura JSON está incorreta. Erros comuns incluem vírgulas faltando, aspas não escapadas ou nomes de campos embed incorretos. Use um validador JSON para verificar a string do payload antes de colá-la no workflow.

Notificações Apenas para Deploys Bem-sucedidos

O exemplo acima usa if: success(), que é acionado apenas quando todas as etapas anteriores são bem-sucedidas. Para enviar uma notificação em caso de falha, adicione uma segunda etapa com if: failure(). Você pode usar a mesma URL do webhook com uma cor de embed e texto de mensagem diferentes. Isso fornece notificações separadas para sucesso e falha sem configuração extra.

Limites de Taxa e Frequência de Mensagens

Os webhooks do Discord têm um limite de taxa de 30 requisições por 60 segundos por webhook. Para a maioria dos workflows de deploy, esse limite nunca é atingido. Se você executar vários workflows em paralelo que usam o mesmo webhook, pode atingir o limite. Nesse caso, crie webhooks separados para canais ou workflows diferentes.

Webhook do Discord vs Notificação Slack do GitHub Actions

Item	Webhook do Discord	Notificação Slack do GitHub Actions
Configuração	Criar webhook nas configurações do canal Discord, sem registro de aplicativo	Requer instalação do aplicativo Slack e token OAuth
Formato do payload	JSON com objeto embed, texto simples ou upload de arquivo	JSON com Slack Block Kit ou anexos legados
Personalização	Cor do embed, campos, autor, miniatura, rodapé	Blocos, botões, menus de seleção, modais
Limite de taxa	30 requisições por 60 segundos	1 mensagem por segundo por canal
Custo	Gratuito com conta Discord	Gratuito com plano gratuito do Slack, mas histórico de mensagens limitado

Após configurar o webhook, você pode expandir a notificação para incluir o nome do autor do commit, um link para o commit e o ambiente de implantação. Os campos do embed suportam até 25 campos, então há espaço para adicionar tempo de build, número de versão ou resultados de teste. Para um sistema de produção, considere usar uma ação dedicada do GitHub, como Ilshidur/action-discord, que encapsula a chamada curl com opções adicionais. Mas o método curl simples oferece controle total sobre o payload e evita dependências de ações de terceiros.