Erro 400 (Bad Request)

O erro HTTP 400 Bad Request indica que o endpoint recebeu a requisição enviada pelo Asaas, porém a aplicação rejeitou o conteúdo recebido por considerar que o payload está inválido ou diferente do esperado.

Na maioria dos casos, o problema não está no envio do webhook, mas sim em alguma validação realizada pela própria aplicação receptora.

O que acontece quando ocorre um erro 400?

Quando o endpoint retorna HTTP 400:

• o evento não é considerado entregue;
• o Asaas inicia novas tentativas de envio;
• a fila passa a sofrer penalização progressiva;
• após 15 falhas consecutivas, a fila será interrompida;
• novos eventos deixam de ser enviados até a reativação da fila.

🚧

Atenção

O erro 400 pode interromper completamente a sincronização entre a sua aplicação e o Asaas caso não seja corrigido.

Principais causas

As situações mais comuns são:

• esperar campos que não existem no payload;
• validar atributos obrigatórios que podem ser nulos;
• desserialização incorreta do JSON;
• rejeição de novos atributos adicionados ao webhook;
• validações excessivamente restritivas;
• tentar converter tipos incorretamente;
• esperar somente determinados eventos;
• utilizar estruturas fixas que não aceitam evolução do payload.

Exemplo de problema comum

Imagine uma aplicação que espera sempre o atributo:

{
  "payment": {
    "subscription": "sub_123"
  }
}

Porém, nem todas as cobranças pertencem a uma assinatura.

Em alguns eventos, o payload pode ser:

{
  "payment": {
    "subscription": null
  }
}

Se a aplicação considerar esse campo obrigatório, poderá retornar HTTP 400.

Outro exemplo comum

Uma aplicação pode esperar apenas determinados atributos:

{
  "id": "evt_xxx",
  "event": "PAYMENT_RECEIVED"
}

Porém, o Asaas pode adicionar novos campos futuramente:

{
  "id": "evt_xxx",
  "event": "PAYMENT_RECEIVED",
  "newAttribute": "value"
}

Caso o parser da aplicação não aceite atributos desconhecidos, a requisição poderá ser rejeitada.

Como identificar o problema

1. Consulte os logs do webhook

Verifique:

• payload enviado;
• horário da tentativa;
• código HTTP retornado;
• quantidade de reenvios.

Veja mais em:

Como visualizar os Logs de Webhooks

2. Compare o payload recebido

Confira a documentação do evento correspondente e valide se a aplicação está preparada para tratar:

• atributos opcionais;
• campos nulos;
• novos atributos;
• diferentes tipos de eventos.

Comportamento dos Webhooks

Os Webhooks podem ser reenviados em caso de falha.

Por isso, recomendamos:

• implementar idempotência;
• não assumir que os eventos serão enviados apenas uma vez;
• processar apenas os campos necessários;
• ignorar atributos desconhecidos.

📘

Importante

O payload dos Webhooks pode evoluir ao longo do tempo. Seu sistema deve estar preparado para aceitar novos atributos sem gerar exceções.

Boas práticas

✅ Aceitar campos opcionais.

✅ Ignorar atributos desconhecidos.

✅ Validar apenas os campos realmente necessários.

✅ Implementar logs na aplicação.

✅ Processar o webhook de forma assíncrona.

✅ Implementar idempotência.

✅ Retornar HTTP 200 após receber o evento com sucesso.

Fluxo de correção

Erro 400
↓
Consultar Logs de Webhooks
↓
Verificar payload recebido
↓
Corrigir validações da aplicação
↓
Testar novamente
↓
Retornar HTTP 200
↓
Fila volta a processar normalmente

Próximos passos

Caso continue encontrando problemas, recomendamos consultar:

• Logs de Webhooks;
• Fila pausada;
• Como reativar fila interrompida;
• Como implementar idempotência em Webhooks;
• Erro 403 (Forbidden);
• Erro 404 (Not Found);
• Erro 408 - Read Timed Out;
• Erro 500 (Internal Server Error);
• Outros erros.