Por que o cache do avatar do webhook do Discord persiste por dias após a atualização

Você atualizou o avatar do seu webhook do Discord, mas a imagem antiga ainda aparece nas mensagens e incorporações. Esse comportamento de cache pode durar de algumas horas a vários dias. O Discord usa cache agressivo para reduzir a carga do servidor e melhorar o desempenho. Este artigo explica por que o cache não é atualizado imediatamente e fornece métodos para forçar uma atualização.

Por que o Discord armazena avatares de webhook em cache

O Discord armazena avatares de webhook em sua rede de entrega de conteúdo (CDN). A CDN serve a mesma imagem para todos os usuários por um período definido chamado TTL (Time to Live). Isso reduz o número de requisições ao servidor de origem e acelera a entrega de imagens. Quando você atualiza um avatar de webhook através da API do Discord ou do portal do desenvolvedor, a alteração é salva no backend do Discord. No entanto, o cache da CDN ainda mantém a versão antiga até que o TTL expire. O TTL padrão para avatares de webhook é entre 24 e 48 horas, mas pode se estender por mais tempo se a imagem for raramente solicitada.

Outro fator é a própria URL do avatar. O Discord gera um hash baseado nos dados da imagem do avatar e no ID do webhook. Se o novo avatar produzir um hash diferente, a CDN o vê como um novo recurso e serve o antigo até que a nova URL seja solicitada. Mas se o hash permanecer idêntico devido a dados de imagem idênticos, o cache não é invalidado. Esse comportamento é proposital para manter o Discord rápido e confiável.

Como funciona a URL do avatar

O formato da URL do avatar é: https://cdn.discordapp.com/avatars/{webhook_id}/{avatar_hash}.{extensão}. O avatar_hash é uma string hexadecimal de 32 caracteres gerada a partir dos dados da imagem. Quando você envia um novo avatar, o Discord gera um novo hash. Mas a CDN armazena em cache o par URL e hash antigos. Até que o TTL do cache expire, as requisições para essa URL retornam a imagem antiga.

Passos para forçar a atualização do cache do avatar do webhook

Você não pode limpar o cache da CDN do Discord diretamente. Mas pode contornar o cache adicionando uma query string única à URL do avatar. Esse método funciona para bots personalizados e scripts que exibem o avatar do webhook.

1. Obtenha a URL atual do avatar do webhook
   Use a API do Discord para buscar o objeto do webhook. Envie uma requisição GET para https://discord.com/api/webhooks/{webhook.id}/{webhook.token}. A resposta inclui o campo avatar com o hash. A URL completa da CDN é https://cdn.discordapp.com/avatars/{webhook.id}/{avatar}.png.
2. Adicione uma query string única
   Adicione um parâmetro de consulta aleatório à URL, como ?v=123456 ou ?t=current_timestamp. Por exemplo: https://cdn.discordapp.com/avatars/{webhook.id}/{avatar}.png?v=1712345678. Isso força o navegador ou o cliente do Discord a tratá-la como uma nova URL e buscar a versão mais recente da CDN.
3. Atualize o avatar novamente via API
   Se o método da query string não funcionar, envie uma imagem de avatar ligeiramente diferente. Use o endpoint Modify Webhook com uma nova imagem. Isso gera um novo hash e URL da CDN. A entrada antiga do cache se torna órfã e a nova imagem aparece após alguns minutos. Envie uma requisição PATCH para https://discord.com/api/webhooks/{webhook.id}/{webhook.token} com um corpo JSON contendo "avatar": "data:image/png;base64,...".
4. Aguarde a expiração natural do cache
   Se você não puder modificar o webhook ou a URL, aguarde 24 a 48 horas. O cache da CDN expira automaticamente. Depois disso, todos os usuários verão o avatar atualizado.

Se o Discord ainda mostrar o avatar antigo

Mesmo após seguir os passos acima, alguns usuários ainda podem ver o avatar antigo devido ao cache local do navegador ou do aplicativo. Abaixo estão problemas comuns e suas soluções.

Avatar antigo aparece no aplicativo desktop do Discord

O aplicativo desktop do Discord armazena avatares em cache localmente. Limpe o cache do aplicativo pressionando Ctrl + Shift + I para abrir as Ferramentas do Desenvolvedor. Vá para a aba Application, selecione Clear Storage e clique em Clear site data. Em seguida, reinicie o Discord. Isso força o aplicativo a buscar o avatar novamente da CDN.

Avatar antigo aparece no navegador

Seu navegador armazena imagens em cache de forma agressiva. Abra as Ferramentas do Desenvolvedor com F12, vá para a aba Network e marque a caixa Disable cache. Recarregue a página. Alternativamente, limpe todo o cache do navegador em Configurações > Privacidade e segurança > Limpar dados de navegação.

Avatar do webhook não atualiza em incorporações

As incorporações do Discord armazenam em cache o avatar do webhook no momento em que a incorporação é gerada. Se você enviou uma mensagem com o webhook antes de atualizar o avatar, a incorporação mostra a imagem antiga. Exclua a mensagem antiga e reenvie-a. Novas incorporações usam o avatar atual da CDN.

Métodos de atualização do avatar do webhook: API vs Portal do Desenvolvedor

Item	API do Discord (Modify Webhook)	Portal do Desenvolvedor do Discord
Velocidade de atualização	Instantânea no backend, atraso da CDN permanece	Instantânea no backend, atraso da CDN permanece
Mudança no hash do avatar	Sim, se os dados da imagem forem diferentes	Sim, se os dados da imagem forem diferentes
Método de bypass do cache	Adicionar query string à URL no código	Não aplicável, sem acesso ao código
Melhor para	Desenvolvedores com scripts de bot	Atualizações manuais via interface web

Após ler este artigo, você entende por que o cache do avatar do webhook do Discord persiste por dias e como forçar uma atualização. Para resultados imediatos, adicione uma query string única à URL do avatar ou reenvie uma imagem ligeiramente diferente. Se você gerencia vários webhooks, considere criar um script que adicione automaticamente um timestamp às URLs dos avatares para evitar atrasos futuros de cache.