Por que a propriedade ‘Token’ do Webhook do Discord não pode ser usada para editar mensagens

Ao enviar uma mensagem por um webhook do Discord, a API retorna um objeto JSON que inclui uma propriedade “token”. Muitos desenvolvedores assumem que esse token pode ser reutilizado para editar ou excluir aquela mensagem posteriormente. Essa suposição leva a erros 403 Forbidden, pois o Discord não aceita o token retornado para endpoints de modificação de mensagens. O token do webhook que permite editar mensagens é o mesmo token usado para criar o webhook, não o retornado na resposta da mensagem. Este artigo explica por que essa incompatibilidade ocorre e como editar mensagens corretamente usando o token original do webhook.

Por que o Discord retorna um token na resposta da mensagem do webhook

Quando você envia uma mensagem por um webhook, o Discord retorna um objeto JSON que contém uma propriedade chamada “token”. Essa propriedade não é um token de segurança para autenticação. É um identificador único para a própria mensagem, usado internamente pelo Discord para rastrear qual webhook a enviou. A documentação da API se refere a isso como “token da mensagem” para distingui-lo do token do webhook.

O token do webhook que concede permissões de edição e exclusão é aquele fornecido quando você criou o webhook. Esse token faz parte da URL do webhook, que se parece com https://discord.com/api/webhooks/123456789/abcDEFghijKLMnoPQRstUV. O segundo segmento após o ID do webhook é o token do webhook. O Discord armazena esse token no servidor e o usa para autenticar qualquer solicitação de edição ou exclusão de mensagens desse webhook.

O token de nível de mensagem retornado em cada resposta não é armazenado pelo Discord para fins de autenticação. É um ID de referência que ajuda o Discord a correlacionar a mensagem ao webhook de origem. Tentar usar esse token em uma chamada de API resulta em um erro 403 Forbidden, pois o sistema de autenticação do Discord não o reconhece como uma credencial válida para o endpoint PATCH /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}.

Como o Discord autentica edições de mensagens de webhook

O Discord exige duas informações para autenticar uma solicitação de edição de mensagem: o ID do webhook e o token do webhook. O ID do webhook identifica qual webhook é o dono da mensagem. O token do webhook prova que seu aplicativo tem permissão para modificar mensagens desse webhook. Ambos devem vir do processo de criação do webhook, não da resposta da mensagem. O formato do endpoint é fixo: PATCH /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}. Se você substituir o token da mensagem pelo token do webhook, o Discord rejeita a solicitação.

Passos para editar corretamente uma mensagem de webhook usando o token original

Para editar uma mensagem enviada por um webhook, você deve armazenar o token do webhook da URL de criação e o ID da mensagem da resposta. Siga estes passos exatamente.

1. Extraia o token do webhook da URL do webhook
   Ao criar um webhook no Discord, a URL contém o ID do webhook e o token do webhook. Por exemplo, em https://discord.com/api/webhooks/123456789/abcDEFghijKLMnoPQRstUV, o token é abcDEFghijKLMnoPQRstUV. Salve este token na configuração ou banco de dados do seu aplicativo.
2. Capture o ID da mensagem da resposta do webhook
   Após enviar uma mensagem pelo webhook, analise o JSON de resposta. A propriedade id é o ID da mensagem. A propriedade token na resposta não é usada. Armazene apenas o ID da mensagem.
3. Construa o endpoint correto da API
   Monte a URL: https://discord.com/api/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}. Substitua {webhook.id} pelo ID numérico da URL do webhook, {webhook.token} pelo token salvo no passo 1 e {message.id} pelo ID do passo 2.
4. Envie uma solicitação PATCH com o conteúdo atualizado
   Use uma solicitação HTTP PATCH para o endpoint do passo 3. Inclua um corpo JSON com os campos que deseja atualizar. Por exemplo, para alterar o conteúdo da mensagem, envie {"content": "Texto da mensagem atualizada"}. Não inclua cabeçalhos de autenticação — o Discord autentica a solicitação usando o token na URL.

Se a edição ainda falhar após usar o token correto

Erro 403 Forbidden ao fazer PATCH na mensagem do webhook

Um erro 403 após usar o token correto do webhook geralmente significa que o token do webhook está incorreto ou expirou. Verifique se o token na sua URL corresponde ao da criação do webhook. Tokens de webhook não expiram a menos que o webhook seja excluído e recriado. Se você regenerou a URL do webhook em Configurações do Servidor > Integrações > Webhooks do Discord, o token muda. Atualize seu token armazenado de acordo.

Erro 400 Bad Request ao enviar o corpo do PATCH

Um erro 400 indica que o corpo da solicitação está malformado ou contém campos inválidos. Certifique-se de que seu JSON é válido e está de acordo com a especificação da API do Discord. Por exemplo, o campo content deve ser uma string, e você não pode atualizar username ou avatar_url após a mensagem ser enviada. Apenas content, embeds, components e attachments podem ser modificados.

Erro 404 Not Found ao usar o ID da mensagem

Um erro 404 significa que o ID da mensagem está incorreto ou a mensagem foi excluída. Verifique se o ID da mensagem foi capturado da resposta correta. Se a mensagem foi excluída por um usuário ou bot, o Discord retorna 404. Você não pode editar uma mensagem excluída.

Item	Token do Webhook (da URL de criação)	Token da Mensagem (do JSON de resposta)
Propósito	Autentica solicitações de API para editar ou excluir mensagens	ID de referência interno para a mensagem
Pode editar mensagens	Sim	Não
Pode excluir mensagens	Sim	Não
Onde encontrar	URL do webhook, segundo segmento do caminho	JSON de resposta, propriedade token
Exemplo de valor	abcDEFghijKLMnoPQRstUV	MTIzNDU2Nzg5MDEyMzQ1Njc4OTA

O sistema de webhooks do Discord usa dois tipos distintos de token para finalidades diferentes. O token do webhook da URL de criação é a única credencial que permite editar e excluir mensagens. O token da mensagem retornado nas respostas é um identificador somente leitura que não pode autenticar nenhuma chamada de API. Sempre armazene o token do webhook da URL, não o da resposta da mensagem. Para uso avançado, considere usar o sistema de webhook de interação do Discord, onde você pode editar mensagens usando PATCH /webhooks/{application.id}/{interaction.token}/messages/@original — este endpoint também requer o token de interação, não um token de resposta de mensagem.