Criar um webhook do Discord para postar mensagens automaticamente

O que é um webhook do Discord?

Um webhook do Discord é uma URL específica de um canal que permite a um serviço externo postar uma mensagem nesse canal enviando uma requisição HTTP, sem fazer login como bot ou como usuário. A própria documentação para desenvolvedores do Discord descreve o endpoint como POST /webhooks/{webhook.id}/{webhook.token} e afirma claramente que "this call does not require authentication" (essa chamada não exige autenticação), porque o id e o token do webhook embutidos na URL são eles mesmos a credencial. Esse único fato explica quase tudo que uma equipe precisa saber sobre a configuração: criar o webhook é uma etapa única e sujeita a permissão dentro do Discord, enquanto usá-lo depois é tão simples quanto enviar JSON para uma URL.

Como criar um webhook do Discord nas configurações do canal?

Um membro do servidor com a permissão Manage Webhooks cria um webhook do Discord a partir das próprias configurações de um canal, na aba Integrações, escolhendo New Webhook e copiando a URL que o Discord gera para ele. A mesma ação está disponível pela API do Discord como POST /channels/{channel.id}/webhooks, para a qual a documentação do Discord afirma que também é necessária a permissão Manage Webhooks nesse canal. Nomeie o webhook e, se precisar, dê a ele um avatar antes de copiar a URL, já que qualquer pessoa com essa URL pode postar no canal a partir desse momento.

Como é o payload JSON de um webhook do Discord?

O payload JSON de um webhook do Discord é o corpo da requisição enviado para a URL do webhook, e no mínimo ele precisa incluir um de content, embeds, poll ou um anexo de arquivo, já que a própria documentação do Discord lista isso como requisito para a chamada de execução do webhook. O campo content carrega texto de mensagem simples com até 2000 caracteres, enquanto username e avatar_url substituem o nome e a imagem padrão do webhook apenas para aquela mensagem, e embeds carrega até 10 objetos de embed ricamente formatados em uma única chamada. O mecanismo é um corpo JSON POST padrão: um serviço monta esse objeto, envia para a URL do webhook via HTTPS, e o Discord posta o resultado no canal em que o webhook foi criado.

{
  "content": "Deployment finished",
  "username": "Release Bot",
  "avatar_url": "https://example.com/bot-avatar.png",
  "embeds": []
}

Quais limites de taxa se aplicam a um webhook do Discord?

O Discord aplica um limite global de 50 requisições por segundo por aplicação em toda a sua API, segundo a própria documentação para desenvolvedores do Discord, e a rota própria de um webhook carrega um limite separado e mais estreito que o Discord comunica por meio de cabeçalhos de resposta em vez de um único número publicado. Cada resposta inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, e a documentação do Discord instrui um cliente a ler esses cabeçalhos em vez de fixar um limite no código, já que os limites por rota estão "subject to change" (sujeitos a mudança). Um serviço que envia muitas mensagens em rajada precisa checar o cabeçalho de requisições restantes depois de cada chamada e pausar assim que ele chegar a zero, em vez de presumir um número fixo de chamadas por minuto.

Por que a URL de um webhook do Discord é um segredo?

A URL de um webhook do Discord é um segredo porque o id e o token dentro dela são toda a credencial que o endpoint verifica, e a própria documentação do Discord confirma que a chamada de execução do webhook não exige autenticação adicional além do que a URL já carrega. Qualquer pessoa que tenha essa URL pode postar qualquer mensagem nesse canal, sob o nome do webhook, sem nunca se autenticar como usuário do Discord ou como bot. Guarde a URL do mesmo jeito que se guarda uma chave de API, como em uma variável de ambiente ou um gerenciador de segredos, e nunca faça commit dela em um repositório de código público nem cole em um script do lado do cliente.

Um webhook do Discord pode receber mensagens, não só enviar?

Um webhook padrão do Discord só envia mensagens para um canal; ele não consegue ler mensagens que outras pessoas postam ali, já que o endpoint de execução do webhook é um destino POST de mão única, sem o acesso de leitura correspondente. Uma equipe que quer reagir ao que acontece dentro de um servidor do Discord, do mesmo jeito que os limites de taxa da API do Reddit regem uma integração de mão dupla com o Reddit, precisa de um bot do Discord com token próprio e as permissões de gateway relevantes. Essa é uma configuração diferente de um webhook, mais parecida com a forma como o preço da API do Twitter regula o acesso de mão dupla aos próprios dados do X, e pertence ao lado de coleta de dados de redes sociais de um projeto, não ao lado de alertas; a documentação para desenvolvedores do Discord, no estilo de um guia de introdução, é a próxima parada certa para uma equipe que constrói um bot completo.

Perguntas frequentes

Posso editar ou excluir uma mensagem que já enviei com um webhook do Discord?

Sim. A resposta da chamada de execução do webhook do Discord retorna um message id quando a requisição inclui ?wait=true, e esse id pode ser usado com endpoints separados de edição e exclusão vinculados ao mesmo webhook. Sem wait=true, a chamada inicial não retorna o objeto de mensagem necessário para uma edição posterior.

Um webhook do Discord expira?

A URL de um webhook do Discord não expira sozinha; ela continua válida até um admin do servidor excluir o webhook ou remover o canal ao qual ele pertence. Como ela nunca expira sozinha, tratar a URL como um segredo permanente, não como um token temporário, é a suposição mais segura.

Mais de um serviço pode usar a mesma URL de um webhook do Discord?

Sim, tecnicamente qualquer número de serviços pode enviar requisições para a mesma URL de webhook, já que o Discord não distingue qual remetente fez a chamada. Na prática, usar um webhook separado por serviço ou por bot facilita rastrear mensagens até a origem delas e permite revogar uma integração sem quebrar outra.

O que acontece se eu enviar um payload maior que os limites do Discord?

O Discord rejeita a requisição com uma resposta de erro em vez de truncar o conteúdo em silêncio, então um payload com mais de 2000 caracteres em content ou mais de 10 objetos em embeds faz a chamada falhar por completo. Checar o código de status da resposta depois de cada chamada ao webhook detecta isso antes de uma mensagem simplesmente nunca chegar.

Criar um webhook do Discord exige especificamente o dono do servidor?

Não. Qualquer membro com a permissão Manage Webhooks em um canal pode criar um webhook ali, e essa permissão pode ser concedida a um cargo sem tornar esse cargo dono ou administrador do servidor. A API do Discord aplica a mesma checagem de permissão no endpoint POST /channels/{channel.id}/webhooks usado para criar um de forma programática.

Um webhook do Discord é a mesma coisa que um bot do Discord?

Não. Um webhook é uma URL de mão única para postar mensagens em um único canal sem login, enquanto um bot é uma aplicação completa com token próprio que consegue ler mensagens, responder a comandos e agir em muitos canais e servidores. Um projeto que só precisa enviar notificações para um canal precisa de um webhook; um projeto que precisa escutar e responder precisa de um bot.

Dá para configurar um webhook do Discord sem escrever código?

Criar um não exige código: um membro do servidor com a permissão Manage Webhooks abre a aba Integrations do canal, clica em New Webhook e copia a URL gerada. Dar um nome ou avatar ao webhook nesse momento é opcional. Para enviar uma mensagem de fato é preciso alguma forma de mandar uma requisição POST via HTTPS com um corpo JSON, seja um script, uma ferramenta de automação ou um serviço que já fale JSON.

Como saber quantas requisições ainda tenho antes de bater no limite de taxa do Discord?

O Discord não publica um número fixo para a rota própria de um webhook; em vez disso, cada resposta traz os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. A própria documentação do Discord diz que um cliente deve ler esses cabeçalhos em vez de fixar um limite no código, já que os limites por rota podem mudar. Um serviço que envia muitas mensagens em rajada confere o cabeçalho de requisições restantes depois de cada chamada e pausa assim que ele chega a zero.

Uma mensagem enviada por webhook pode parecer que veio de outra pessoa?

Os campos username e avatar_url do payload JSON substituem o nome e a imagem padrão do webhook, mas só para aquela mensagem. O nome e o avatar configurados do webhook continuam os mesmos em tudo o mais. Isso permite que um webhook publique como "Release Bot" para um aviso de deploy e com outro nome na próxima vez, sem editar o webhook em si.

O que impede outra pessoa de postar no meu canal se ela conseguir minha URL de webhook?

Nada. O id e o token do webhook embutidos na URL são toda a credencial que o Discord verifica, então qualquer pessoa com essa URL pode postar qualquer mensagem no canal sob o nome do webhook, sem nunca fazer login como usuário ou bot. Por isso a URL deve ser tratada como uma API key: guardada em uma variável de ambiente ou em um gerenciador de segredos, nunca commitada em um repositório público nem colada em código do lado do cliente.