Você recebe um erro “Falha na Entrega do Webhook do Discord com 401” quando seu sistema automatizado tenta enviar uma mensagem para um canal do Discord. Esse código de status 401 significa que a requisição não foi autorizada. O Discord rejeitou o webhook porque o token de autenticação estava ausente, inválido ou expirado. Este artigo explica as três principais causas desse erro e como resolver cada uma.
Principais Conclusões: Corrigindo o Erro 401 do Webhook
- Token da URL do webhook não corresponde: O token na sua requisição não corresponde ao token que o Discord emitiu para aquele webhook.
- Webhook expirado ou excluído: O webhook foi removido do canal ou o token expirou devido a uma alteração na configuração do servidor.
- Método HTTP ou endpoint incorreto: Usar uma requisição POST para a URL errada ou usar uma requisição GET em vez de POST.
Por que o Discord Retorna um Erro 401 para Webhooks
Uma URL de webhook do Discord contém um ID único e um token. A estrutura é https://discord.com/api/webhooks/<webhook_id>/<webhook_token>. Quando sua aplicação envia uma requisição POST para esta URL, o Discord verifica se o token corresponde ao token armazenado para aquele ID de webhook. Se o token estiver errado, ausente ou o webhook não existir mais, o Discord retorna HTTP 401 Não Autorizado.
O erro 401 não é um problema de rede ou de servidor. É uma falha de autenticação. O Discord não retorna 401 para limitação de taxa ou limites de tamanho de payload. Esses retornam 429 ou 413. O erro 401 sempre aponta para um problema de credencial.
Causa 1: Token do Webhook Não Corresponde ao ID
A causa mais comum é um erro de copiar e colar. Quando você cria um webhook em Configurações do Servidor > Integrações > Webhooks, o Discord gera uma URL. Se você editar manualmente essa URL, pode alterar um caractere no token. O token diferencia maiúsculas de minúsculas. Um único caractere errado causa um 401.
Causa 2: Webhook Foi Excluído ou Regenerado
Se alguém com permissão Gerenciar Webhooks excluir o webhook, a URL se torna inválida. Qualquer requisição POST para essa URL retorna 401. Da mesma forma, se um moderador regenerar o token do webhook, o token antigo para de funcionar. O ID do webhook permanece o mesmo, mas o novo token substitui o antigo.
Causa 3: Método HTTP ou Endpoint Errado
Os webhooks do Discord aceitam apenas requisições POST. Enviar uma requisição GET para a URL do webhook retorna 401. Além disso, usar o endpoint errado, como /api/webhooks/<id> sem o token, dispara um 401. O endpoint completo deve incluir tanto o ID quanto o token.
Passos para Diagnosticar e Corrigir o Erro 401 do Webhook
Passo 1: Verifique a URL do Webhook no Discord
- Abra as Configurações do Servidor
Clique com o botão direito no nome do servidor na lista de canais. Selecione Configurações do Servidor no menu de contexto. - Vá para Integrações
Na barra lateral esquerda, clique em Integrações. Em Webhooks, clique no webhook que está falhando. - Copie a URL do webhook
Clique em Copiar URL do Webhook. Não edite esta URL. Cole-a diretamente na configuração da sua aplicação.
Passo 2: Verifique se Houve Regeneração do Token
- Abra os detalhes do webhook
Siga o Passo 1 para abrir a página do webhook em Integrações. - Procure pelo aviso de token regenerado
Se alguém clicou em Regenerar, o Discord mostra um aviso: “A URL do webhook foi regenerada. A URL antiga não funcionará mais.” Atualize sua aplicação com a nova URL.
Passo 3: Teste o Webhook com cURL
- Abra um terminal
No Windows, pressione Win+R, digitecmde pressione Enter. No macOS ou Linux, abra o Terminal. - Execute o comando cURL
Digite:curl -X POST -H "Content-Type: application/json" -d '{"content":"teste"}' SUA_URL_DO_WEBHOOK. Substitua SUA_URL_DO_WEBHOOK pela URL exata do Discord. Se você receber um 401, a URL está errada ou o webhook foi excluído.
Passo 4: Confirme que o Webhook Existe
- Verifique a lista de webhooks
Em Configurações do Servidor > Integrações, role até a seção Webhooks. Se o webhook estiver ausente, alguém o excluiu. Crie um novo webhook. - Crie um novo webhook
Clique em Criar Webhook. Dê um nome e atribua um canal. Clique em Copiar URL do Webhook. Use esta nova URL na sua aplicação.
Passo 5: Certifique-se de que Está Usando POST
- Verifique o código da sua aplicação
Procure pelo método HTTP no seu script. Deve ser POST. Se você usar GET, PUT ou DELETE, o Discord retorna 401. - Verifique a URL do endpoint
Certifique-se de que a URL termina com/api/webhooks/<id>/<token>. Não adicione segmentos extras como/slackou/githuba menos que esteja usando o endpoint compatível com Slack do Discord. Esse endpoint é/api/webhooks/<id>/<token>/slacke ainda requer o token.
Se o Discord Ainda Retornar 401 Após a Correção Principal
URL do Webhook Contém Quebras de Linha ou Espaços
Ao copiar a URL do webhook do Discord, o navegador pode adicionar uma nova linha no final. Esse caractere extra quebra o token. Cole a URL em um editor de texto simples como o Bloco de Notas. Remova quaisquer espaços ou quebras de linha antes de salvar a URL na configuração da sua aplicação.
Aplicação Armazena em Cache a URL Antiga do Webhook
Algumas aplicações armazenam em cache valores de configuração. Após atualizar a URL do webhook, reinicie a aplicação ou limpe o cache. Por exemplo, em um bot do Discord usando discord.py, reinicie o processo do bot. Em um pipeline CI/CD como GitHub Actions, faça um novo commit para disparar uma nova build.
Nível de Boost do Servidor Afeta os Limites de Webhooks
O Discord limita o número de webhooks por canal com base no nível de boost do servidor. Se o seu servidor tiver menos de 10 webhooks por canal, isso não é um problema. Exceder o limite não causa um erro 401. Isso faz com que o Discord rejeite a criação do webhook, não a entrega. Se você não conseguir criar um novo webhook, verifique o limite de webhooks do canal em Configurações do Servidor > Integrações.
Métodos de Autenticação de Webhook do Discord: Token vs OAuth2
| Item | Token do Webhook | Token de Bot OAuth2 |
|---|---|---|
| Tipo de autenticação | Token no caminho da URL | Token Bearer no cabeçalho Authorization |
| Escopo de acesso | Apenas um único canal | Todos os canais que o bot tem acesso |
| Rotação de token | Regeneração manual na interface | Automática via Portal do Desenvolvedor do Discord |
| Erro em token inválido | HTTP 401 Não Autorizado | HTTP 401 Não Autorizado com código de erro 50001 |
| Caso de uso | Postagem simples de mensagens de serviços externos | Interação completa do bot com comandos e embeds |
Os webhooks do Discord usam um token simples embutido na URL. Esse token não expira a menos que seja regenerado. Tokens de bot OAuth2 exigem um client ID e secret e podem ser revogados no portal do desenvolvedor. Para envio simples de mensagens, webhooks são mais fáceis de configurar. Para recursos interativos, use um bot.
Para resolver um erro 401, comece copiando a URL do webhook diretamente de Configurações do Servidor > Integrações. Teste com cURL usando uma requisição POST. Se o teste for bem-sucedido, atualize a configuração da sua aplicação. Se o teste falhar, o webhook foi excluído ou o token foi regenerado. Crie um novo webhook e atualize todas as referências. Evite editar a URL manualmente. Use a URL exata fornecida pelo Discord.