Webhook returns HTTP 400

Symptoms

• The provider marks the delivery as failed and records a 400 response.
• The route is reached, but processing stops before business logic.
• Application logs show JSON parsing, validation, or signature errors.

Likely causes

• The body is empty, truncated, or larger than the receiver limit.
• The Content-Type does not match the parser used by the route.
• Signature verification uses a parsed or transformed body.
• The payload schema changed or the handler requires fields that are optional for some event types.
• A proxy or middleware rewrites the body before it reaches the route.

How to diagnose HTTP 400

1. Read the exact response body recorded by the provider. Replace generic 400 responses with safe, specific error categories in server logs.
2. Capture the request headers and raw body at ingress before application parsing.
3. Confirm Content-Type, Content-Length, character encoding, and decompression behavior.
4. Run signature verification before JSON parsing when the provider signs raw bytes.
5. Validate the payload according to event type and version rather than one global schema.
6. Send a new test event and confirm the route reaches the intended processing branch.

Use status codes deliberately

Verify the fix

The same payload shape should pass parsing and validation, a newly delivered event should receive the intended 2xx response, and logs should show which validation stage accepted the request.