Como Usar Webhook do Discord com OAuth2 para Autorização de Aplicativos

Webhooks do Discord permitem enviar mensagens automáticas para canais de texto sem um bot completo. O OAuth2 é o padrão do Discord para autorizar aplicativos de terceiros a acessar dados do usuário. Combinar ambos permite criar um sistema seguro onde um app externo envia notificações para um canal específico do Discord somente após o usuário conceder permissão via OAuth2. Este artigo explica como configurar um aplicativo Discord, gerar uma URL de autorização OAuth2 e usar o token de acesso resultante para enviar mensagens via webhook.

Como Funciona a Autorização de Webhook do Discord com OAuth2

Webhooks do Discord são endpoints HTTP simples que aceitam payloads JSON. Normalmente você cria um webhook manualmente nas configurações de Integrações de um canal e copia sua URL. Essa URL contém um ID e token únicos que qualquer pessoa pode usar para postar mensagens sem autenticação adicional.

O OAuth2 adiciona uma camada de consentimento do usuário. Em vez de compartilhar uma URL de webhook estática, seu aplicativo solicita permissão de um usuário do Discord para criar um webhook em nome dele. O usuário clica em um link de autorização, faz login e aprova o escopo webhook.incoming. O Discord então retorna um token de acesso que seu app pode usar para criar um webhook em um canal específico escolhido pelo usuário.

Pré-requisitos

Antes de começar, você precisa de um aplicativo Discord registrado no Portal do Desenvolvedor. Também precisa de um servidor web ou uma função serverless que possa lidar com requisições HTTP e armazenar tokens com segurança. O usuário que autoriza o aplicativo deve ter a permissão Gerenciar Webhooks no servidor Discord de destino.

Passos para Autorizar um Webhook Usando OAuth2

Este processo tem três fases: criar a URL de autorização, trocar o código por um token e usar o token para enviar uma mensagem via webhook.

Fase 1: Gerar a URL de Autorização OAuth2

1. Abra o Portal do Desenvolvedor Discord
   Acesse https://discord.com/developers/applications e faça login com sua conta Discord.
2. Selecione seu aplicativo
   Clique no aplicativo que deseja usar. Se não tiver criado um, clique em New Application, dê um nome e confirme.
3. Navegue até as configurações de OAuth2
   Na barra lateral esquerda, clique em OAuth2. Na aba General, você vê o Client ID e o Client Secret. Copie o Client ID — você precisa dele para a URL de autorização.
4. Adicione uma URI de redirecionamento
   Role para baixo até Redirects. Clique em Add Redirect e insira a URL para onde o Discord enviará o código de autorização. Para testes locais, use http://localhost:3000/callback. Clique em Save Changes.
5. Monte a URL de autorização
   Use o URL Generator no topo da página OAuth2. Selecione o escopo webhook.incoming. Em Redirect URL, escolha o redirecionamento que você acabou de adicionar. O gerador mostra uma URL como esta:
   https://discord.com/api/oauth2/authorize?client_id=SEU_CLIENT_ID&redirect_uri=SUA_REDIRECT_URI&response_type=code&scope=webhook.incoming
   Copie esta URL. Quando um usuário a visitar, o Discord pedirá que ele selecione um servidor e um canal onde o webhook será criado.

Fase 2: Trocar o Código de Autorização por um Token de Acesso

1. Lide com o redirecionamento
   Após o usuário aprovar a autorização, o Discord redireciona o navegador dele para sua URI de redirecionamento com um parâmetro de consulta code. Por exemplo: http://localhost:3000/callback?code=abc123.
2. Envie uma requisição POST para o endpoint de token
   Seu backend deve trocar este código por um token de acesso. Envie uma requisição POST para https://discord.com/api/oauth2/token com os seguintes parâmetros no corpo (use dados de formulário codificados na URL):
   client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&grant_type=authorization_code&code=abc123&redirect_uri=SUA_REDIRECT_URI
3. Analise a resposta
   O Discord retorna um objeto JSON contendo access_token, token_type (sempre Bearer), expires_in, refresh_token e um objeto webhook. O objeto webhook inclui id, type, name, avatar, channel_id e url. A url é a URL completa do webhook que você usará para enviar mensagens.
4. Armazene o token e a URL do webhook
   Salve o access_token e o webhook.url em seu banco de dados. O token expira após 7 dias. Use o refresh_token para obter um novo token sem pedir que o usuário reautorize.

Fase 3: Enviar uma Mensagem via Webhook Usando o Webhook Autorizado

1. Prepare o payload JSON
   Crie um objeto JSON com um campo content. Por exemplo:
   { "content": "Olá do seu webhook autorizado!" }
   Você também pode incluir campos embeds, username e avatar_url.
2. Envie a requisição POST
   Use qualquer cliente HTTP para enviar uma requisição POST para a URL do webhook que você armazenou. A URL se parece com:
   https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN
   Defina o cabeçalho Content-Type como application/json. Nenhuma autenticação adicional é necessária porque a própria URL do webhook é a credencial.
3. Verifique a resposta
   Se a requisição for bem-sucedida, o Discord retorna 204 No Content. Se você receber um 400 Bad Request, verifique se seu JSON é válido. Um 404 significa que o webhook foi excluído ou o token está errado.

Erros Comuns e Limitações

Webhook Não Aparece na Resposta do Token

Se a resposta do token não incluir um objeto webhook, o usuário não completou o fluxo de autorização corretamente. A causa mais comum é que o usuário não selecionou um canal durante a tela de consentimento OAuth2. Lembre o usuário de escolher um canal antes de clicar em Authorize.

Token de Acesso Expira Antes de Enviar uma Mensagem

O token de acesso expira após 7 dias. Depois de obter a URL do webhook, você não precisa mais do token de acesso para enviar mensagens. A URL do webhook é permanente, a menos que o webhook seja excluído. Armazene a URL do webhook imediatamente após o fluxo OAuth2 e use-a diretamente.

Usuário Não Consegue Selecionar o Servidor ou Canal

O usuário deve ter a permissão Gerenciar Webhooks no servidor onde deseja criar o webhook. Se o menu suspenso de servidores estiver vazio, o usuário não tem essa permissão em nenhum servidor que possua ou gerencie. Peça ao usuário para verificar suas funções no servidor de destino.

Escopo Bot vs Escopo Webhook.incoming

Não confunda o escopo bot com webhook.incoming. O escopo bot adiciona um usuário bot ao servidor, o que requer permissões adicionais e um token de bot. O escopo webhook.incoming apenas cria um webhook — nenhum usuário bot é adicionado. Use webhook.incoming quando você só precisa enviar mensagens programaticamente.

Escopo Webhook OAuth2 vs Escopo Bot

Item	Escopo webhook.incoming	Escopo bot
O que cria	Uma URL de webhook para enviar mensagens	Um usuário bot que entra no servidor
Permissões necessárias	Gerenciar Webhooks no canal de destino	Definidas no inteiro de permissão do bot
Método de autenticação	URL do webhook (ID + token)	Token do bot do Portal do Desenvolvedor
Pode ler mensagens	Não	Sim, com intents apropriados
Pode editar/excluir mensagens	Não	Sim, se as enviou
Consentimento do usuário necessário	Sim, via autorização OAuth2	Sim, via autorização OAuth2
Melhor para	Notificações, logs, postagem simples de mensagens	Comandos interativos, moderação, lógica complexa

Use o escopo webhook.incoming quando seu aplicativo precisar apenas enviar mensagens para um canal do Discord e não precisar ler ou interagir com usuários. Use o escopo bot quando precisar de um bot interativo completo que possa ouvir eventos, responder a comandos e gerenciar recursos do servidor.

O fluxo OAuth2 para o escopo bot é idêntico ao fluxo do webhook, exceto que o valor do escopo é bot e você também deve especificar o parâmetro permissions como um inteiro bitwise. O token retornado é um token de bot, não uma URL de webhook. Você pode combinar ambos os escopos em uma única requisição de autorização separando-os por um espaço, por exemplo: scope=bot webhook.incoming.

Agora você pode configurar um webhook do Discord autorizado via OAuth2 para seu aplicativo. Os passos principais são gerar a URL de autorização correta com o escopo webhook.incoming, lidar com o callback para trocar o código por um token e armazenar a URL do webhook para envio futuro de mensagens. Para uso em produção, implemente a renovação do token com o refresh_token para evitar pedir que os usuários reautorizem a cada 7 dias. Você também pode combinar o escopo webhook.incoming com outros escopos como identify para acessar informações adicionais do usuário no mesmo fluxo OAuth2.