Erro 400 (Bad Request)

O erro 400 Bad Request indica que a requisição do Webhook chegou ao endpoint, mas foi rejeitada durante a validação ou interpretação do conteúdo recebido.

Nesse cenário, verifique principalmente o parser, as validações e a estrutura esperada pela sua aplicação.

Principais causas

O erro pode ocorrer quando a aplicação:

• espera campos que não existem no payload;
• trata campos opcionais ou nulos como obrigatórios;
• não consegue desserializar o JSON;
• rejeita atributos desconhecidos;
• possui validações excessivamente restritivas;
• tenta converter valores para tipos incompatíveis;
• aceita somente determinados eventos;
• utiliza estruturas fixas que não permitem a evolução do payload.

Verifique campos opcionais e nulos

Nem toda cobrança pertence a uma assinatura. Uma aplicação pode esperar:

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

Mas receber:

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

Se payment.subscription for tratado como obrigatório, o endpoint pode rejeitar o evento com HTTP 400.

Valide como obrigatórios somente os campos necessários para a regra de negócio e trate valores nulos previstos pelo recurso.

Aceite novos atributos no payload

Uma aplicação pode estar preparada para receber:

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

O payload pode receber novos atributos ao longo do tempo:

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

O parser não deve rejeitar a requisição apenas porque recebeu um atributo que ainda não é utilizado pela aplicação.

Como identificar a causa

1. Consulte os Logs de Webhooks

Acesse Logs de Webhooks e localize a tentativa que retornou HTTP 400.

Verifique:

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

2. Compare o payload com o evento correspondente

Confirme se a aplicação está preparada para tratar:

• atributos opcionais;
• campos nulos;
• atributos ainda não utilizados pela integração;
• diferentes eventos configurados no Webhook.

Consulte a página específica do evento em Eventos de Webhooks.

3. Revise os logs da sua aplicação

Utilize o horário da tentativa registrado nos Logs de Webhooks para localizar a requisição no seu sistema.

Verifique em qual etapa ocorreu a rejeição, como:

• desserialização;
• validação de campos;
• conversão de tipos;
• validação do evento;
• regra de negócio executada durante a requisição.

Corrija e valide o endpoint

Após identificar a causa:

1. ajuste o parser ou a validação responsável pelo HTTP 400;
2. permita campos opcionais, nulos e atributos desconhecidos quando aplicável;
3. persista o evento antes de iniciar processamentos demorados;
4. responda HTTP 200 após confirmar a persistência;
5. execute regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once. Utilize o id do evento para impedir que uma retentativa gere processamento duplicado.

Consulte como implementar idempotência em Webhooks.

Fluxo de correção

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Identificar HTTP 400"] --> B["Consultar Logs de Webhooks"]
    B --> C["Verificar o payload"]
    C --> D["Corrigir parser ou validações"]
    D --> E["Testar novamente"]
    E --> F{"A fila está interrompida?"}

    F --> FSim(("Sim"))
    F --> FNao(("Não"))

    FSim --> G["Reativar a fila"]
    FNao --> H["Aguardar nova entrega"]

    G --> I["Confirmar HTTP 200"]
    H --> I

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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
    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B,C,D,E,G,H validacao
    class F decisao
    class I sucesso

    class FSim respostaSim
    class FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#22C55E,stroke-width:4px
    linkStyle 6 stroke:#EF4444,stroke-width:4px

O que acontece enquanto o erro persiste

Cada resposta HTTP 400 é considerada uma falha de entrega.

Com falhas consecutivas:

• o mesmo evento pode ser enviado novamente;
• a configuração entra no mecanismo de penalização progressiva;
• após 15 falhas consecutivas, a fila do Webhook é interrompida;
• enquanto estiver interrompida, novos eventos ficam armazenados e deixam de ser enviados.

Se a fila já estiver interrompida, corrija o erro antes de reativá-la.

Entenda a Penalização de filas.

Consulte como reativar uma fila interrompida.

Próximos passos

• Consulte os Logs de Webhooks
• Conheça os Eventos de Webhooks
• Implemente idempotência em Webhooks
• Entenda a Penalização de filas
• Reative uma fila interrompida
• Consulte outros erros de Webhooks