DiscordStatus
Guias / Guides

Erro 500 (Internal Server Error)

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

O que significa

O erro 500 (Internal Server Error) nos logs de Webhooks indica que o Asaas conseguiu estabelecer conexão com o seu endpoint, enviou a requisição corretamente, mas a própria aplicação retornou uma falha interna durante o processamento.

Em outras palavras, o webhook chegou até o seu sistema, porém ocorreu alguma exceção ou erro inesperado que impediu a conclusão do processamento.

Como funciona

Quando um evento ocorre no Asaas, é enviada uma requisição POST para o endpoint configurado.

Se sua aplicação responder com:

  • HTTP 200: o evento é considerado entregue com sucesso;
  • qualquer outro código (400, 403, 404, 408, 500, etc.): a tentativa é considerada uma falha.

No caso do erro 500, significa que o problema ocorreu dentro da sua própria aplicação.

Quando esse erro acontece

As causas mais comuns são:

  • exceções não tratadas no código;
  • falhas de conexão com banco de dados;
  • indisponibilidade de APIs externas;
  • problemas de autenticação com serviços terceiros;
  • consultas SQL com erro;
  • problemas de memória ou CPU;
  • serialização incorreta do payload recebido;
  • dependências indisponíveis;
  • timeout em chamadas internas;
  • falhas em filas ou workers.

Impacto na integração

Enquanto o endpoint continuar retornando HTTP 500:

  • os eventos continuarão sendo reenviados automaticamente;
  • a fila sofrerá penalizações progressivas;
  • após 15 falhas consecutivas, a fila será interrompida;
  • novos eventos continuarão sendo acumulados;
  • eventos permanecem armazenados por até 14 dias;
  • eventos não processados após esse período serão excluídos permanentemente.

Por isso, é importante corrigir o problema rapidamente.

Exemplo de cenário comum

Fluxo:

Asaas
↓
POST webhook
↓
Aplicação recebe evento
↓
Consulta banco de dados
↓
Banco indisponível
↓
Exceção não tratada
↓
HTTP 500
↓
Webhook entra em retentativa

Nesse caso, o problema não está na comunicação com o Asaas, mas na própria aplicação.

Como investigar

1. Consultar os logs da aplicação

O primeiro passo é verificar os logs do servidor.

Exemplos comuns:

NullReferenceException
Database connection timeout
SQL syntax error
Connection refused
Out of memory

A causa exata normalmente estará registrada nos logs.

2. Validar se o payload está sendo tratado corretamente

Com o tempo, novos atributos podem ser adicionados aos objetos enviados pelo Asaas.

Seu código deve estar preparado para ignorar propriedades desconhecidas e evitar exceções de desserialização.

📘

Importante

A adição de novos atributos em Webhooks não representa quebra de contrato. Sua aplicação deve ser tolerante a campos adicionais.

3. Validar dependências externas

Verifique:

  • banco de dados;
  • Redis;
  • RabbitMQ;
  • filas internas;
  • APIs externas;
  • serviços de autenticação;
  • serviços de e-mail.

Muitas vezes o erro 500 ocorre porque uma dependência intermediária está indisponível.

4. Testar o endpoint localmente

Utilize Postman ou outra ferramenta para enviar o mesmo payload recebido pelo webhook.

Se o erro ocorrer novamente, será possível identificar a origem da exceção.

Boas práticas

  • responder HTTP 200 rapidamente;
  • processar tarefas pesadas em segundo plano;
  • implementar tratamento de exceções;
  • registrar logs detalhados;
  • monitorar CPU, memória e banco de dados;
  • evitar dependências externas síncronas no processamento do webhook;
  • implementar idempotência;
  • utilizar alertas e monitoramento da aplicação.

Erros comuns

  • assumir que o payload nunca mudará;
  • depender de APIs externas durante o processamento;
  • não tratar exceções;
  • interromper o processamento por campos opcionais nulos;
  • não registrar logs;
  • retornar HTTP 500 para qualquer falha de regra de negócio.

Como validar se funcionou

Após corrigir o problema:

  1. Reative a fila de Webhooks.
  2. Gere um novo evento.
  3. Consulte os logs do Asaas.

Se tudo estiver correto:

  • os eventos voltarão a ser entregues normalmente;
  • os erros 500 deixarão de aparecer;
  • a fila será processada em ordem cronológica.

Conteúdos relacionados