Webhook do Discord: como criar e enviar mensagens

Guia de webhook do Discord

Webhook do Discord: como criar, payload JSON, embeds | We.Inc

Crie um webhook do Discord, monte o payload JSON (content, username, avatar_url, embeds) com limites de caracteres ao vivo e copie código pronto em curl, JavaScript e Python.

Um webhook do Discord é uma URL secreta ligada a um canal. Faça um POST com um corpo JSON contendo content (até 2000 caracteres), embeds (até 10) ou os dois, e a mensagem aparece nesse canal com o nome do webhook. Não é preciso bot nem login, e é justamente por isso que qualquer pessoa com a URL consegue postar.

Os campos do Execute Webhook que você mais vai usar

Campo
Tipo
Observações

Texto da mensagem, até 2000 caracteres

Substitui o nome do webhook nesta mensagem

Substitui o avatar do webhook nesta mensagem

Até 10 objetos de embed

Limita quais @menções realmente notificam

thread_id (query)
Posta em uma thread do canal

wait (query)
true retorna a mensagem criada em vez de 204

Os webhooks são o jeito mais rápido de enviar alertas, envios de formulário ou avisos de deploy para um canal do Discord. O gerador abaixo escreve o JSON para você, conta os caracteres em relação aos limites do Discord enquanto você digita e transforma o resultado em curl, JavaScript e Python para colar em um script ou servidor. Ele mesmo não envia nada, então a URL do seu webhook nunca sai da sua máquina.

Nas configurações do seu servidor do Discord, crie um webhook para o canal onde quer postar.
Escolha o canal, defina um nome e um avatar e depois copie a URL do webhook.
Preencha o gerador abaixo e copie o código gerado.
Rode o código em um terminal ou no seu servidor, com a URL em uma variável de ambiente.

Trate a URL como uma senha. Guarde-a em uma variável de ambiente e fora do código de front-end e de repositórios públicos.
Se uma URL vazar, apague esse webhook nas configurações do servidor e crie um novo; a URL antiga deixa de funcionar.
Defina allowed_mentions como { "parse": [] } quando o content incluir dados digitados por usuários, para que ninguém consiga disparar um @everyone.
Adicione ?wait=true quando precisar receber de volta o id da mensagem, por exemplo para editá-la ou apagá-la depois.
A cor do embed é um inteiro decimal, então a cor hex 4F98FB é enviada como 5216507.

Perguntas frequentes

Como consigo a URL de um webhook do Discord?

Você precisa da permissão Gerenciar webhooks no servidor ou no canal. Nas configurações do seu servidor do Discord, crie um webhook para o canal e copie a URL dele.

Por que meu webhook retorna 400 Bad Request?

Geralmente o corpo está vazio ou inválido. Você precisa enviar pelo menos um destes: content, embeds, components, um arquivo ou uma enquete, e o content precisa ter 2000 caracteres ou menos. Envie também o cabeçalho Content-Type: application/json, senão o corpo não é lido como JSON.

Posso chamar um webhook do Discord pelo navegador?

Não faça isso. Qualquer página que faça isso expõe a URL a todos os visitantes, que passam a poder postar qualquer coisa no seu canal. Envie a partir de um servidor, de uma função serverless ou de um script, e faça a sua página chamar esse ponto.

Quais são os limites dos embeds?

O Discord documenta um título de até 256 caracteres, valores de campo de até 1024 caracteres e um total combinado de 6000 caracteres somando título, descrição, nomes e valores dos campos, texto do rodapé e nome do autor em todos os embeds de uma mensagem.

Um webhook consegue ler mensagens ou responder a usuários?

Não. Um webhook só consegue postar (e editar ou apagar as próprias mensagens). Ler canais, reagir a comandos ou responder a pessoas exige um aplicativo de bot.

O que a URL contém

A URL de um webhook termina em duas partes: o id do webhook e o token dele. O token é a única credencial, e é por isso que a documentação do Discord observa que executar um webhook não exige nenhuma outra autenticação. Quem tem a URL completa tem o mesmo poder que você.

Content, embeds ou os dois

O content simples serve para alertas curtos e aceita o markdown do Discord. Os embeds trazem uma barra lateral colorida, um título com link, campos dispostos em colunas e um rodapé, o que fica mais legível para dados estruturados, como um pedido ou um relatório de erro.
Você pode enviar os dois em uma chamada. O content aparece acima dos embeds, e o allowed_mentions decide se os nomes citados nele realmente notificam as pessoas.

Enviando em grande volume

Quando você envia rápido demais, o Discord responde com status 429 e um valor JSON retry_after em segundos. Respeite esse valor e coloque as mensagens em fila, em vez de tentar de novo em um loop apertado. Juntar vários eventos em uma mensagem com vários embeds também reduz o número de chamadas.

Requisições prontas

curl: uma mensagem simples

A URL é lida de uma variável de ambiente, para nunca ir parar no histórico do shell nem em um commit.

Node.js: um embed com campos

Usa o fetch nativo do Node 18 em diante. wait=true faz o Discord retornar a mensagem para você registrar o id dela.

Python com requests

json= define o cabeçalho Content-Type para você. Um status 204 significa que a mensagem foi postada.

Gerador de payload para webhook do Discord

Digite a mensagem e o embed, acompanhe a contagem de caracteres e copie o JSON ou o código. Nada é enviado a partir desta página.

Conteúdo da mensagem

Substituir nome de usuário

Substituir URL do avatar

Adicionar um embed

Título do embed

Descrição do embed

Cor do embed

Texto do rodapé

Bloquear todas as menções (allowed_mentions parse: [])

Caracteres do embed: {n} / 6000

Acima do limite: o Discord vai rejeitar isto.

Vazio: adicione conteúdo ou um embed.

Formato de saída

Pré-visualização aproximada

Webhook

Comece grátis · Sem cartão de crédito