Webhook do Discord vs bot: qual usar

Webhook e bot parecem a mesma coisa, porque os dois fazem uma mensagem aparecer num canal do Discord. A diferença está no sentido da comunicação. O webhook é uma porta de entrada: você faz um POST e a mensagem aparece. O bot é um participante: ele recebe eventos, decide o que fazer e responde.

Escolher errado custa tempo. Quem sobe um bot só para avisar "deploy concluído" mantém um processo ligado sem necessidade. Quem tenta fazer comandos com webhook descobre tarde que ele não escuta nada.

O que é um webhook do Discord?#

É uma URL que o Discord gera para um canal (em Configurações do canal, Integrações, Webhooks). Você a chama com POST /webhooks/{id}/{token}, sem cabeçalho de autenticação: o token dentro da URL já é a credencial. Qualquer pessoa com a URL consegue postar no canal.

Pela API, o webhook aceita content (até 2000 caracteres), embeds (até 10 por mensagem), arquivos, enquetes e username e avatar_url para trocar o nome e a foto de cada mensagem. Você precisa enviar ao menos um entre conteúdo, embeds, componentes, arquivo ou enquete. Com ?wait=true a API devolve a mensagem criada, e com thread_id ela posta numa thread.

Exemplo mínimo com curl:

curl -X POST "$DISCORD_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deploy concluído", "username": "CI"}'

O mesmo em Node.js, com o fetch nativo e sem nenhuma biblioteca (salve como .mjs, por causa do await fora de função):

const res = await fetch(process.env.DISCORD_WEBHOOK_URL + "?wait=true", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    embeds: [{ title: "Novo pedido", description: "Pedido #1234 pago", color: 0x57f287 }],
  }),
});

if (res.status === 429) {
  const { retry_after } = await res.json();
  console.error(`Limite atingido, tente em ${retry_after}s`);
} else if (!res.ok) {
  console.error("Falhou:", res.status, await res.text());
}

O que é um bot do Discord?#

É um aplicativo com usuário próprio, criado no Portal de Desenvolvedores, que se autentica com um token. Ele pode se conectar ao Gateway (uma conexão WebSocket) e receber eventos em tempo real: mensagens, entrada de membros, reações, comandos de barra. Também pode receber interações por HTTP, se você configurar uma Interactions Endpoint URL, sem manter o Gateway aberto. Com essa URL configurada, as interações deixam de chegar pelo Gateway. Cada requisição no endpoint HTTP traz os cabeçalhos X-Signature-Ed25519 e X-Signature-Timestamp, e você precisa validar a assinatura.

O bot pode fazer quase tudo que um membro faz: gerenciar cargos, moderar, tocar áudio, exibir menus e botões. Para criar um, veja como fazer um bot do Discord.

Webhook ou bot: qual a diferença na prática?#

Um detalhe sobre leitura: um bot sem a intent privilegiada MESSAGE_CONTENT recebe content vazio nas mensagens, com exceções como mensagens que mencionam o bot, mensagens diretas com ele e as que ele mesmo envia. Detalhes em intents privilegiadas.

Quando usar só um webhook?#

Escolha webhook quando o fluxo é de uma via e o gatilho vem de fora do Discord:

• alertas de monitoramento, falha de build ou deploy concluído;
• notificação de venda, cadastro ou pagamento;
• feed de RSS, commits ou changelog num canal;
• um script de cron que posta um resumo diário.

A vantagem é a simplicidade. Não há token de bot, intents, nem reconexão. O custo é que o webhook só conhece o canal: não sabe quem está lá, não ouve resposta e não passa por permissões de cargo.

Quando você precisa de um bot?#

Precisa de bot assim que o Discord vira a entrada do fluxo:

• comandos de barra (/ticket, /play), botões e menus;
• moderação, boas-vindas, cargos automáticos;
• respostas que dependem do usuário, do histórico ou de um banco de dados;
• música, voz ou qualquer coisa que use o Gateway;
• mensagens em vários servidores ou canais escolhidos em tempo de execução.

Se o bot deve responder 24 horas por dia, ele precisa de um processo sempre ligado. Veja como manter um bot do Discord 24/7.

Quais limites afetam cada um?#

O limite global da API é de 50 requisições por segundo por bot, e as rotas têm limites próprios que o Discord pede para não fixar no código. Requisições sem cabeçalho de autorização, como as de webhook, são limitadas por IP. Ao estourar, a API responde 429 com retry_after em segundos. Espere o tempo indicado no cabeçalho Retry-After ou no campo antes de repetir. O exemplo acima já lê o campo. Mais em erro 429 do Discord.

Outro cuidado: se um webhook devolver 404, pare de usá-lo (provavelmente foi apagado). A documentação manda não insistir, porque tentativas repetidas levam a restrição temporária.

Os limites de conteúdo são os mesmos nos dois: 2000 caracteres de texto, 10 embeds por mensagem e 6000 caracteres somados nos textos dos embeds.

Dá para combinar os dois?#

Dá, e muitos projetos fazem isso. O bot cuida de comandos e eventos dentro do servidor. Os sistemas externos (CI, gateway de pagamento, monitor) mandam alertas por webhook, sem depender de o bot estar online naquele momento. Se o bot cair, os alertas continuam chegando.

Uma regra prática: comece com webhook se só precisa avisar. Migre para bot quando surgir a primeira necessidade de ler ou responder.

Como fazer isso na Square Cloud#

O webhook não precisa de hospedagem, mas o código que o dispara precisa rodar em algum lugar. Já o bot de Gateway precisa de um processo sempre ligado. Na Square Cloud, os containers não entram em modo de suspensão, e o reinício automático (ligado por padrão no deploy pelo painel) traz o bot de volta quando o processo encerra com erro.

Você faz o deploy do bot em Node.js, Python, Java ou outro runtime, por ZIP no painel, pela CLI, pelo GitHub ou pela extensão do VS Code. A RAM do plano é um pool compartilhado entre suas aplicações, com mínimo de 256 MB por aplicação de fundo, como um bot. O plano Hobby custa a partir de R$ 12,49 por mês. Guarde o token do bot e a URL do webhook como variáveis de ambiente da aplicação, não no código.

Para começar, veja a página de hospedagem de bots do Discord.