Como Enviar um Webhook do Discord com Embed em Python

Você precisa enviar uma mensagem formatada para um canal do Discord usando um webhook, e deseja que a mensagem inclua um embed com conteúdo rico como título, descrição, cor e campos. Webhooks do Discord permitem que aplicações externas publiquem mensagens sem uma conta de bot, mas o corpo JSON padrão do Discord não cria embeds automaticamente. Este artigo explica como construir e enviar uma mensagem de webhook com um embed usando a biblioteca Python requests. Você aprenderá a estrutura exata do payload JSON e verá um exemplo de código completo.

Entendendo a Estrutura do Embed de Webhook do Discord

Um webhook do Discord aceita um payload JSON via uma requisição HTTP POST. O payload pode conter uma string content para texto simples e um array embeds para objetos de embed ricos. Cada objeto embed suporta vários subobjetos que controlam seu layout: title, description, url, color (inteiro decimal), fields (array de pares nome-valor inline ou não inline), footer, image, thumbnail e author. O campo color aceita um inteiro que representa um código de cor hexadecimal convertido para decimal. Por exemplo, hex #00ff00 se torna decimal 65280.

Antes de escrever código, você precisa de uma URL de webhook. Abra o Discord e vá em Configurações do Servidor > Integrações > Webhooks. Crie um novo webhook ou copie a URL de um existente. A URL se parece com https://discord.com/api/webhooks/1234567890/abcdef. Mantenha esta URL privada — qualquer pessoa com ela pode postar no seu canal.

A biblioteca Python requests lida com o HTTP POST. Instale-a com pip install requests se ainda não o fez. O script definirá um dicionário JSON com os dados do embed, converterá para uma string JSON e enviará para a URL do webhook. O Discord retorna um status 204 No Content em caso de sucesso.

Código Python para Enviar um Webhook com Embed

O código a seguir envia uma mensagem de webhook com um único embed que inclui título, descrição, cor, campos, rodapé e timestamp. Substitua YOUR_WEBHOOK_URL pela sua URL real de webhook.

1. Importe a biblioteca requests
   No topo do seu script Python, adicione import requests. Isso dá acesso ao método post().
2. Armazene a URL do webhook
   Atribua a URL a uma variável: webhook_url = "https://discord.com/api/webhooks/1234567890/abcdef". Use uma string literal.
3. Construa o dicionário do embed
   Crie um dicionário com os campos do embed. Por exemplo:

embed = {
    "title": "Atualização de Status do Servidor",
    "description": "Todos os sistemas estão operacionais agora.",
    "color": 65280,
    "fields": [
        {
            "name": "Tempo de Atividade",
            "value": "99,9%",
            "inline": True
        },
        {
            "name": "Usuários Ativos",
            "value": "1.234",
            "inline": True
        }
    ],
    "footer": {
        "text": "Bot de Status"
    },
    "timestamp": "2025-03-15T12:00:00Z"
}

4. Empacote o embed em um dicionário de payload
   Crie o payload principal: data = {"embeds": }. A chave embeds deve conter uma lista de dicionários de embed. Você pode incluir múltiplos embeds adicionando mais dicionários à lista.
5. Envie a requisição POST
   Chame response = requests.post(webhook_url, json=data). O parâmetro json converte automaticamente o dicionário para JSON e define o cabeçalho Content-Type como application/json.
6. Verifique o status da resposta
   Imprima o código de status: print(response.status_code). Um 204 significa sucesso. Um 400 indica um payload malformado. Um 404 significa que a URL do webhook é inválida ou o webhook foi excluído.

Aqui está o script completo em um bloco:

import requests

webhook_url = "https://discord.com/api/webhooks/1234567890/abcdef"

embed = {
    "title": "Atualização de Status do Servidor",
    "description": "Todos os sistemas estão operacionais agora.",
    "color": 65280,
    "fields": [
        {
            "name": "Tempo de Atividade",
            "value": "99,9%",
            "inline": True
        },
        {
            "name": "Usuários Ativos",
            "value": "1.234",
            "inline": True
        }
    ],
    "footer": {
        "text": "Bot de Status"
    },
    "timestamp": "2025-03-15T12:00:00Z"
}

data = {"embeds": }

response = requests.post(webhook_url, json=data)
print(response.status_code)

Erros Comuns e Limitações

A Cor do Embed Deve Ser um Inteiro Decimal

Um erro comum é passar uma string hexadecimal como "#00ff00" ou uma tupla RGB. O Discord espera um inteiro. Converta hex para decimal com Python: int("00ff00", 16) produz 65280. Use um conversor online ou a expressão Python para obter o valor correto.

Campos do Embed Excedem os Limites do Discord

Cada embed pode ter até 25 campos. O limite total de caracteres do embed é de 6000 caracteres em todos os campos e descrição. Se seu payload exceder esses limites, o Discord retorna um erro 400. Reduza a descrição ou remova campos desnecessários.

URL do Webhook Contém Barra no Final

Se você incluir acidentalmente uma barra no final da URL do webhook, a requisição pode falhar com um 404. Remova qualquer barra final antes de usar a URL no seu script.

Timestamp Deve Estar no Formato ISO 8601

O campo timestamp espera uma string no formato ISO 8601, como "2025-03-15T12:00:00Z" ou "2025-03-15T12:00:00+00:00". Use datetime.now(timezone.utc).isoformat() do Python para gerar um timestamp válido dinamicamente.

Não Há Suporte para Anexos em Embeds de Webhook

Embeds de webhook não podem incluir anexos de arquivos. Para enviar uma imagem, use os campos image ou thumbnail do embed com uma URL apontando para uma imagem hospedada externamente. O Discord exibirá a imagem inline no embed.

Campos do Embed do Webhook: Obrigatórios vs Opcionais

Campo	Obrigatório	Descrição
title	Não	Texto em negrito no topo do embed
description	Não	Texto principal abaixo do título
color	Não	Cor da borda esquerda como inteiro decimal
fields	Não	Array de pares nome-valor com opção inline
footer	Não	Objeto com texto e icon_url opcional
timestamp	Não	String de timestamp ISO 8601
image	Não	Objeto com url para uma imagem grande
thumbnail	Não	Objeto com url para uma imagem pequena no canto superior direito
author	Não	Objeto com name, url e icon_url

Agora você pode enviar um webhook do Discord com um embed em Python. Comece copiando o script acima e substituindo a URL do webhook e o conteúdo do embed pelos seus próprios dados. Para formatação avançada, adicione um objeto author com nome e URL do ícone, ou use image e thumbnail para incluir visuais. Lembre-se de converter cores hexadecimais para inteiros e manter o payload total dentro do limite de caracteres do Discord.