The raw-body trap: why JSON body parsers break webhook signature verification

What it is

A webhook signature is an HMAC over a specific byte string the provider sent. Anything between the TCP socket and your verification code that touches those bytes — a generic JSON parser, a proxy that re-encodes the body, a logging middleware that reads and buffers it — can invalidate the signature, even when the parsed data looks identical afterwards, because whitespace, key order and Unicode escaping are not preserved by a parse-then-reserialise round trip. Each framework exposes the untouched bytes differently. Express's body-parser docs describe a verify option "called as verify(req, res, buf, encoding), where buf is a Buffer of the raw request body" — the standard way to capture bytes even when express.json() runs. FastAPI/Starlette's Request exposes an awaitable Request.body() that returns raw bytes, as shown in FastAPI's own example overriding async def body(self) -> bytes. Flask's Request.get_data(cache=True, as_text=False, parse_form_data=False) "reads the buffered incoming data from the client into one bytes object," but "if the form data was already parsed this method will not return anything". Django's HttpRequest.body is "the raw HTTP request body as a bytestring," and accessing it after request.read()/readline() (or after multipart request.POST parsing) "will produce a RawPostDataException" with the message You cannot access body after reading from request's data stream. Go's net/http gives only an io.Reader (r.Body); it must be drained with io.ReadAll and buffered before any json.NewDecoder(r.Body).Decode() call, since a decoder consumes the reader.

Why it matters

This is one of the most common causes of "signature verification failed" reports (alongside a wrong secret), and it is invisible in casual testing: unit tests that construct requests in-process often bypass the exact middleware chain production traffic goes through.

How to apply

• Mount webhook routes so the raw-body capture happens before, or instead of, generic JSON parsing — in Express, register express.raw({type: "application/json"}) (or a verify callback) on that specific route ahead of any app-wide express.json().
• In FastAPI, read await request.body() for signature checks and parse JSON yourself afterwards from the same bytes, rather than trusting a Body(...)-decoded model for verification.
• In Flask, call get_data() before touching request.json or request.form.
• In Django, read request.body before any code path that calls request.POST, request.read() or a DRF parser on the same request.
• In Go, body, _ := io.ReadAll(r.Body), verify against body, then json.Unmarshal(body, &v) or wrap it in bytes.NewReader(body) for a decoder.

Pitfalls

Fixing this only in the happy path and leaving a shared, app-wide JSON middleware mounted ahead of the webhook route for every other request. Re-encoding the body to "pretty" JSON for logs and accidentally verifying against the reformatted copy. Assuming the bytes after a decompression step are what the provider signed: body-parser's inflate option (on by default) decompresses gzip/deflate/br before verify sees the buffer, so check which representation your provider signs before relying on it.