DiscordStatus
Guias / Guides

Erro 404 (Not Found)

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

O erro 404 Not Found nos Logs de Webhooks indica que a requisição chegou ao domínio configurado, mas o servidor não encontrou a rota utilizada pelo Webhook.

Isso normalmente ocorre quando a URL está incorreta, foi alterada ou deixou de existir.

Principais causas

Verifique se ocorreu alguma destas situações:

  • erro de digitação na URL configurada;
  • alteração da rota sem atualização do Webhook;
  • remoção da rota responsável pelo recebimento;
  • mudança de domínio;
  • mudança de ambiente, como Produção ou homologação;
  • aplicação publicada em outro caminho;
  • proxy ou gateway encaminhando a requisição para uma rota incorreta.

Por exemplo, se o Webhook estiver configurado com:

https://minhaapi.com/webhook

mas a aplicação passou a utilizar:

https://minhaapi.com/api/webhook

a URL anterior poderá retornar HTTP 404.

Como corrigir

1. Confira a URL configurada

Compare a URL cadastrada no Webhook com a rota atualmente publicada pela aplicação.

URL incorreta

https://minhaapi.com/webhook

URL correta

https://minhaapi.com/api/webhook

Verifique:

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

Se a rota foi alterada, atualize a URL configurada no Webhook.

2. Teste a rota com POST

Utilize Postman, cURL ou outra ferramenta HTTP para testar o mesmo método utilizado pelos Webhooks.

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

Se a resposta continuar sendo:

404 Not Found

verifique o roteamento da própria aplicação, proxy ou gateway.

Abrir a URL diretamente no navegador pode ajudar a verificar se o endereço está acessível, mas não valida o comportamento da rota para requisições POST.

3. Confirme se a rota ainda existe

Uma nova versão da aplicação pode alterar o caminho do endpoint.

Antes:

POST /webhook

Depois:

POST /api/webhook

Nesse caso, atualize a configuração do Webhook para utilizar a nova rota.

4. Confirme se a rota aceita POST

Os eventos de Webhook são enviados por requisições POST.

Confirme que:

  • a rota existe;
  • o método POST está habilitado;
  • proxies ou gateways encaminham a requisição para o destino correto;
  • não existe redirecionamento para outra URL.
📘

Importante

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

Exemplo de erro após alteração da rota

A aplicação utilizava:

https://api.minhaempresa.com/webhook

Após uma atualização, passou a utilizar:

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

Se a configuração do Webhook não for atualizada, o fluxo pode resultar em:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas envia o Webhook"] --> B["POST /webhook"]
    B --> C["Servidor retorna<br/>404 Not Found"]
    C --> D["Realizar retentativas"]
    D --> E["Atingir 15 falhas consecutivas"]
    E --> F["Interromper a fila"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Enquanto o 404 persistir, o evento não será considerado entregue e novas tentativas poderão ocorrer.

Após 15 falhas consecutivas, a fila do Webhook é interrompida. Novos eventos continuam sendo gerados e armazenados, mas eventos que permanecerem pendentes por mais de 14 dias são excluídos permanentemente.

Entenda a Penalização de filas.

Como validar a correção

Depois de corrigir a rota:

  1. atualize a URL do Webhook, se necessário;
  2. teste o endpoint novamente com uma requisição POST;
  3. se a fila estiver interrompida, reative a configuração;
  4. gere ou aguarde um novo evento;
  5. consulte os Logs de Webhooks.

A correção está concluída quando as novas tentativas deixam de retornar 404 e o endpoint responde HTTP 200.

Próximos passos

Updated 9 days ago

Did this page help you?