Como Enviar um Webhook do Discord a Partir de uma GitHub Action

Webhooks do Discord permitem que mensagens automáticas sejam postadas em um canal de texto. GitHub Actions podem acionar esses webhooks para enviar notificações sobre eventos do repositório. Você pode querer alertar sua equipe sobre um deploy bem-sucedido, uma build falha ou um novo pull request. Este artigo explica como configurar um webhook do Discord e integrá-lo a uma GitHub Action usando curl e GitHub Secrets.

O problema central é que GitHub Actions não têm acesso direto ao Discord. Você precisa de uma forma de passar a URL do webhook de forma segura e enviar um payload JSON formatado corretamente. Este guia cobre a configuração do webhook no Discord, armazenamento da URL como um GitHub Secret e a escrita de uma etapa do workflow que envia a notificação.

Ao final, você terá um workflow funcional que publica uma mensagem personalizada no seu canal do Discord sempre que um evento específico do GitHub ocorrer. Você também aprenderá a lidar com erros comuns e personalizar o conteúdo da mensagem.

Entendendo Webhooks do Discord e GitHub Actions

Um webhook do Discord é uma URL que aceita requisições HTTP POST com um corpo JSON. Quando você envia uma requisição para essa URL, o Discord publica o conteúdo da mensagem no canal de texto associado. GitHub Actions é uma plataforma de CI/CD que executa workflows em resposta a eventos do repositório, como pushes, pull requests ou releases.

A combinação permite automatizar notificações. Por exemplo, quando um desenvolvedor faz push de código para a branch principal, uma GitHub Action pode compilar o projeto e então enviar um webhook para o Discord dizendo “Build bem-sucedida para o commit abc123.” A URL do webhook deve ser mantida em segredo, pois qualquer pessoa com essa URL pode publicar mensagens no seu canal.

Pré-requisitos

Antes de escrever o workflow, você precisa de:

• Permissão de Administrador ou Gerenciar Webhooks no servidor Discord.
• Um repositório GitHub com pelo menos um arquivo de workflow (YAML em .github/workflows/).
• Familiaridade básica com sintaxe YAML e formato JSON.

Estrutura do Payload JSON

Webhooks do Discord aceitam um objeto JSON com estes campos comuns:

• content (string): O texto principal da mensagem, até 2000 caracteres.
• username (string): Substitui o nome de exibição do webhook.
• avatar_url (string): Substitui a imagem do avatar do webhook.
• embeds (array): Mensagens mais ricas com título, descrição, campos, cor, etc.

Para notificações simples, o campo content é suficiente. Você pode incluir formatação Markdown como negrito, itálico e `código`.

Passos para Enviar um Webhook do Discord a Partir de uma GitHub Action

1. Crie um Webhook no Discord
   Abra o Discord e vá para o seu servidor. Clique no nome do servidor no canto superior esquerdo, depois selecione Configurações do Servidor > Integrações > Webhooks. Clique em Novo Webhook. Dê um nome como “Notificações GitHub” e selecione o canal de texto de destino. Clique em Copiar URL do Webhook e salve em um local seguro. Você não poderá ver a URL completa novamente após fechar a página.
2. Adicione a URL do Webhook como um GitHub Secret
   Vá para o seu repositório GitHub. Clique em Configurações > Segredos e variáveis > Actions. Clique em Novo segredo do repositório. Defina o nome como DISCORD_WEBHOOK e cole a URL no campo valor. Clique em Adicionar segredo. O segredo será mascarado nos logs e não poderá ser lido por usuários não autorizados.
3. Crie ou Edite um Arquivo de Workflow
   No seu repositório, navegue até .github/workflows/. Crie um novo arquivo, por exemplo discord-notify.yml. Use o modelo YAML abaixo. O workflow é acionado em push para a branch main. Você pode alterar o gatilho para pull_request, release ou qualquer evento do GitHub.
4. Escreva a Etapa do Workflow que Envia o Webhook
   Dentro do job, adicione uma etapa que execute um comando curl. Use a variável secrets.DISCORD_WEBHOOK para referenciar a URL. O payload JSON deve incluir um campo content com sua mensagem. Exemplo:
   curl -H "Content-Type: application/json" -d '{"content": "Deploy bem-sucedido!"}' ${{ secrets.DISCORD_WEBHOOK }}
5. Teste o Workflow
   Faça commit e push do arquivo de workflow para a branch main. Vá para a aba Actions no seu repositório e acompanhe a execução do workflow. Se a etapa for bem-sucedida, você verá uma mensagem no seu canal do Discord. Se falhar, verifique os logs do workflow para detalhes do erro.

Exemplo Completo de Workflow

Aqui está um arquivo de workflow completo que envia uma notificação a cada push para a branch principal:

name: Discord Notification
on:
  push:
    branches: [ main ]
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Send Discord webhook
        run: |
          curl -H "Content-Type: application/json" \
          -d '{"content": "Novo push para a branch main por ${{ github.actor }}: ${{ github.event.head_commit.message }}"}' \
          ${{ secrets.DISCORD_WEBHOOK }}

Este workflow usa github.actor para o nome do usuário e github.event.head_commit.message para a mensagem do commit. Você pode personalizar essas variáveis.

Erros Comuns e Limitações

URL do Webhook Exposta nos Logs

Se você acidentalmente imprimir a URL do webhook em uma etapa do workflow, o GitHub a mascara como nos logs. No entanto, a URL ainda é enviada como cabeçalho. Para segurança, nunca codifique a URL diretamente no arquivo de workflow. Sempre use segredos.

Tamanho do Payload Excede o Limite

Webhooks do Discord têm um limite de 2000 caracteres para o campo content. Para mensagens mais longas, use embeds, que permitem até 6000 caracteres em vários campos. Se você exceder o limite, o webhook retorna um erro 400 Bad Request.

Limitação de Taxa

O Discord aplica limites de taxa aos endpoints de webhook. Se você enviar muitas requisições em um curto período, pode receber uma resposta 429 Too Many Requests. Adicione um atraso entre as requisições ou agrupe mensagens. Para a maioria dos casos de uso de CI/CD, uma requisição por execução de workflow é segura.

Webhook Excluído ou Renomeado

Se alguém excluir ou renomear o webhook no Discord, a URL se torna inválida. O workflow falhará com um erro 404 Not Found. Verifique as integrações do servidor Discord para confirmar que o webhook ainda existe.

Métodos de Notificação por Webhook do Discord: curl vs Ação Oficial

Item	Comando curl	Ação Oficial do GitHub (ex.: Ilshidur/action-discord)
Complexidade de configuração	Mínima: única etapa run	Requer adicionar uma ação de terceiros ao seu workflow
Flexibilidade	Controle total sobre o payload JSON, cabeçalhos e tratamento de erros	Limitado aos parâmetros que a ação expõe
Dependências	Nenhuma: curl está pré-instalado nos runners Ubuntu	A ação pode ter dependências ou exigir uma versão específica
Segurança	Segredos são usados diretamente no comando	A ação lida com segredos através de entradas
Manutenção	Você controla o código; nenhuma atualização externa necessária	A ação pode se tornar obsoleta ou quebrar com mudanças no GitHub

Agora você pode enviar webhooks do Discord a partir de uma GitHub Action usando um simples comando curl e um segredo. Comece com uma notificação básica e depois adicione embeds para mensagens mais ricas. Para uso avançado, considere usar uma ação oficial do GitHub se preferir uma sintaxe declarativa. Sempre teste seu workflow em uma branch que não seja de produção primeiro para evitar spam no seu canal do Discord.