Corrigir Bloco de Código Markdown de Webhook do Discord Mostrando Texto Simples

Os webhooks do Discord são uma forma poderosa de enviar mensagens automatizadas de serviços externos para seus canais. No entanto, você pode perceber que blocos de código markdown — destinados a exibir código formatado ou texto monoespaçado — aparecem como texto simples e sem formatação. Isso geralmente acontece porque o payload do webhook não inclui o cabeçalho Content-Type correto ou usa um método de formatação não suportado. Este artigo explica por que os blocos de código falham ao renderizar e fornece etapas exatas para corrigir o problema, tanto para payloads JSON quanto para integrações de terceiros.

Por que os Webhooks do Discord Exibem Blocos de Código como Texto Simples

Os webhooks do Discord aceitam payloads JSON que contêm um campo content. Quando você inclui três crases (```) nesse campo, o analisador de mensagens do Discord deve convertê-las em um bloco de código estilizado. Se o bloco de código aparecer como texto simples, a causa raiz é quase sempre uma das três coisas:

Cabeçalho Content-Type Incorreto

O endpoint do webhook espera que a requisição tenha um cabeçalho Content-Type definido como application/json. Se você enviar o payload como text/plain ou application/x-www-form-urlencoded, o Discord trata todo o corpo como texto bruto e não analisa o markdown. Os delimitadores do bloco de código se tornam caracteres literais.

Escape JSON Incorreto

Dentro de uma string JSON, as barras invertidas devem ser escapadas. Se o seu bloco de código contiver barras invertidas (comuns em caminhos do Windows ou regex), você precisa escrever \\ em vez de \. Além disso, as quebras de linha dentro do campo content devem ser representadas como \n — não quebras de linha reais no corpo JSON. Se você usar quebras de linha literais, o JSON fica malformado e o Discord pode ignorar o markdown.

Formatação de Serviços de Terceiros

Serviços como GitHub, GitLab ou ferramentas de monitoramento enviam webhooks usando sua própria estrutura de payload. Alguns serviços envolvem o código em tags HTML <pre> ou usam um sabor diferente de markdown. O Discord não renderiza HTML; ele processa apenas markdown no estilo Discord. Se o serviço enviar <pre>código</pre>, você verá as tags como texto simples.

Passos para Corrigir a Renderização de Blocos de Código em Webhooks do Discord

Siga estes passos para garantir que o payload do seu webhook renderize blocos de código corretamente. As instruções se aplicam a qualquer cliente HTTP (curl, Postman ou um script personalizado).

1. Defina o cabeçalho Content-Type como application/json
   Ao enviar a requisição, inclua o cabeçalho Content-Type: application/json. Sem isso, o Discord trata o corpo como texto simples e ignora o markdown. No curl, use -H "Content-Type: application/json". No Postman, selecione a aba “Body”, escolha “raw” e defina o formato como “JSON”.
2. Envolva o código em três crases com um identificador de linguagem
   Dentro do campo content, escreva seu bloco de código como:
   ```python\nprint("Hello")\n```
   O identificador de linguagem (por exemplo, python, javascript, bash) ativa o realce de sintaxe. Sem ele, o bloco ainda renderiza como texto monoespaçado, mas sem cores. Sempre inclua uma quebra de linha (\n) após as crases de abertura e antes das crases de fechamento.
3. Escape barras invertidas e quebras de linha na string JSON
   Em JSON, cada barra invertida deve ser duplicada. Por exemplo, um caminho do Windows C:\Users\Nome se torna C:\\Users\\Nome. As quebras de linha devem ser escritas como \n — não quebras de linha reais. Um payload correto se parece com:
   {"content": "```\nC:\\Users\\Nome\n```"}
4. Teste com um payload mínimo usando curl
   Execute este comando em um terminal, substituindo WEBHOOK_URL pela URL do seu webhook:
   curl -H "Content-Type: application/json" -X POST -d '{"content":"```\nHello\n```"}' WEBHOOK_URL
   Se a mensagem mostrar um bloco de código com “Hello”, a correção funciona. Caso contrário, verifique novamente o cabeçalho e o escape.
5. Se estiver usando um serviço de terceiros, modifique o payload antes de enviar
   Se você não puder alterar o webhook de saída do serviço, use um serviço intermediário como Zapier, Make ou uma função serverless personalizada para transformar o payload. Por exemplo, substitua <pre>...</pre> por ```...``` e defina o cabeçalho Content-Type correto.

Se os Webhooks do Discord Ainda Mostrarem Texto Simples Após a Correção Principal

URL do Webhook Contém uma Barra Final ou Caracteres Extras

Uma URL de webhook malformada pode fazer com que o Discord rejeite o payload ou ignore a formatação. Certifique-se de que a URL termine exatamente com /slack ou /github, dependendo do tipo de integração. Para webhooks personalizados, a URL deve se parecer com https://discord.com/api/webhooks/123456/abc123, sem barras extras ou parâmetros de consulta.

Payload Excede os Limites de Caracteres

O Discord limita uma mensagem de webhook a 2000 caracteres. Se o seu bloco de código ultrapassar esse limite, o Discord trunca a mensagem e pode remover as crases de fechamento, fazendo com que o bloco apareça como texto simples. Divida a saída longa em várias chamadas de webhook ou use o campo embeds, que permite até 6000 caracteres por embed.

Usando o Tipo de Webhook Errado (Compatível com Slack vs Personalizado)

O Discord suporta webhooks compatíveis com Slack no endpoint /slack. Se você enviar um payload formatado para Slack para um webhook personalizado (ou vice-versa), o markdown pode não ser analisado corretamente. Para webhooks personalizados, use sempre o campo content. Para webhooks compatíveis com Slack, use o campo text. Verifique a URL do seu webhook: se terminar com /slack, use o formato Slack.

Formatos de Payload de Webhook: Personalizado vs Compatível com Slack

Item	Webhook Personalizado	Webhook Compatível com Slack
Sufixo do endpoint	Nenhum (URL de webhook simples)	/slack anexado à URL do webhook
Campo principal para conteúdo	content	text
Suporte a markdown	Markdown completo do Discord	Markdown do Slack (limitado)
Sintaxe de bloco de código	“`linguagem“`	“`linguagem“` (mesmo, mas pode exigir mrkdwn_in: ["text"])
Cabeçalho Content-Type	application/json	application/json

Webhooks do Discord que exibem blocos de código como texto simples são quase sempre causados por um cabeçalho Content-Type ausente ou incorreto, escape JSON inadequado ou um serviço de terceiros enviando formatação não suportada. Ao definir o cabeçalho corretamente, usar três crases com um identificador de linguagem e escapar barras invertidas e quebras de linha, você pode restaurar a renderização adequada dos blocos de código. Para problemas persistentes, verifique o tipo de URL do webhook e os limites de caracteres. Como dica avançada, use o objeto embed do Discord com o campo description para incluir trechos de código mais longos sem quebrar o markdown.