DiscordStatus
Guias / Guides

Erro 404 (Not Found)

O que fazer quando vejo este erro nos logs de Webhooks do Asaas?

O que significa

O erro 404 (Not Found) nos logs de Webhooks indica que a requisição enviada pelo Asaas chegou ao domínio configurado, porém o caminho (endpoint) informado não foi encontrado pelo servidor.

Em outras palavras, a URL configurada para receber os eventos não existe mais, foi alterada ou está incorreta.

Exemplo:

https://minhaapi.com/webhook

Se a aplicação foi alterada e passou a utilizar:

https://minhaapi.com/api/webhook

o endereço antigo retornará HTTP 404 e os eventos deixarão de ser processados.

Quando esse erro acontece

As causas mais comuns são:

  • erro de digitação na URL cadastrada;
  • alteração do endpoint da aplicação sem atualização no Asaas;
  • remoção da rota responsável pelo webhook;
  • mudança de domínio;
  • mudança de ambiente (produção ou homologação);
  • aplicação publicada em outro caminho;
  • proxy ou gateway redirecionando incorretamente as requisições.

Impacto na integração

Enquanto o endpoint continuar retornando HTTP 404:

  • os eventos não serão processados;
  • o Asaas continuará realizando novas tentativas conforme a política de penalização;
  • após 15 falhas consecutivas, a fila será interrompida;
  • novos eventos continuarão sendo gerados e acumulados;
  • eventos que permanecerem mais de 14 dias sem processamento serão excluídos permanentemente.

Por isso, é importante corrigir o problema o quanto antes.

Como resolver

1. Validar a URL configurada

Verifique se a URL cadastrada no webhook corresponde exatamente ao endpoint disponível em sua aplicação.

Exemplo:

URL incorreta

https://minhaapi.com/webhook

URL correta

https://minhaapi.com/api/webhook

Verifique:

  • protocolo (https);
  • domínio;
  • porta utilizada;
  • caminho da rota;
  • letras maiúsculas e minúsculas;
  • possíveis barras adicionais (/).

2. Testar o endpoint manualmente

Abra a URL no navegador ou utilize ferramentas como Postman ou cURL.

Exemplo:

curl -X POST https://minhaapi.com/api/webhook

Se a resposta retornar:

404 Not Found

o problema está na própria aplicação e não no Asaas.

3. Verificar se a rota ainda existe

Em algumas situações, após uma nova publicação da aplicação, a rota utilizada anteriormente pode ter sido alterada.

Exemplo:

Antes:

POST /webhook

Depois:

POST /api/webhook

Se isso acontecer, basta atualizar a URL configurada no Asaas.

4. Validar se o endpoint aceita requisições POST

Os Webhooks do Asaas são enviados através de requisições POST.

Certifique-se de que:

  • a rota existe;
  • ela aceita o método POST;
  • não existem regras redirecionando a requisição para outro endereço.
📘

Importante

O Asaas considera o webhook entregue com sucesso apenas quando recebe HTTP 200 como resposta.

Exemplo de cenário comum

A aplicação possuía o endpoint:

https://api.minhaempresa.com/webhook

Após uma atualização, o endpoint passou para:

https://api.minhaempresa.com/api/webhook

Como a configuração do webhook no Asaas não foi atualizada, todas as tentativas passaram a retornar HTTP 404.

Resultado:

Asaas
↓
POST /webhook
↓
404 Not Found
↓
Retentativas automáticas
↓
Fila interrompida

Solução:

  • atualizar a URL do webhook;
  • reativar a fila;
  • permitir que os eventos acumulados sejam reenviados.

Boas práticas

  • manter URLs de webhook estáveis;
  • evitar alterar endpoints em produção sem atualizar o Asaas;
  • monitorar os logs do servidor;
  • utilizar ambientes separados para homologação e produção;
  • testar a rota após novas publicações;
  • implementar monitoramento do endpoint.

Como validar se funcionou

Após corrigir o problema:

  1. Atualize a URL do webhook, se necessário.
  2. Reative a fila interrompida.
  3. Gere um novo evento.
  4. Consulte os logs de Webhooks.

Se tudo estiver correto:

  • os eventos voltarão a ser processados;
  • a fila será esvaziada gradualmente;
  • os logs deixarão de apresentar erro 404.

Conteúdos relacionados