Die Raw-Body-Falle: Warum JSON-Body-Parser die Prüfung von Webhook-Signaturen scheitern lassen

Worum es geht

Eine Webhook-Signatur ist ein HMAC über eine bestimmte Bytefolge, die der Anbieter gesendet hat. Alles, was zwischen dem TCP-Socket und dem Prüfcode auf diese Bytes zugreift – ein generischer JSON-Parser, ein Proxy, der den Body neu kodiert, eine Logging-Middleware, die ihn liest und puffert –, kann die Signatur ungültig machen. Das gilt selbst dann, wenn die geparsten Daten danach identisch aussehen, denn Leerzeichen, Schlüsselreihenfolge und Unicode-Escaping bleiben beim Parsen und erneuten Serialisieren nicht erhalten. Jedes Framework stellt die unveränderten Bytes auf eigene Weise bereit. Die Dokumentation von body-parser in Express beschreibt eine Option verify, die wie folgt aufgerufen wird: "called as verify(req, res, buf, encoding), where buf is a Buffer of the raw request body" – der übliche Weg, die Bytes auch dann zu erfassen, wenn express.json() läuft. In FastAPI/Starlette bietet Request die awaitable Methode Request.body(), die die Rohbytes zurückgibt; FastAPI zeigt dies in einem eigenen Beispiel, das async def body(self) -> bytes überschreibt. Zu Request.get_data(cache=True, as_text=False, parse_form_data=False) in Flask heisst es: "reads the buffered incoming data from the client into one bytes object", allerdings: "if the form data was already parsed this method will not return anything". In Django ist HttpRequest.body "the raw HTTP request body as a bytestring"; ein Zugriff darauf nach request.read()/readline() (oder nach dem Multipart-Parsing von request.POST) "will produce a RawPostDataException" mit der Meldung You cannot access body after reading from request's data stream. net/http in Go liefert nur einen io.Reader (r.Body); dieser muss mit io.ReadAll vollständig gelesen und gepuffert werden, bevor json.NewDecoder(r.Body).Decode() aufgerufen wird, da ein Decoder den Reader verbraucht.

Warum es wichtig ist

Neben einem falschen Secret ist dies eine der häufigsten Ursachen für Meldungen wie "signature verification failed", und bei oberflächlichen Tests bleibt das Problem unsichtbar: Unit-Tests, die Requests im selben Prozess erzeugen, umgehen oft genau die Middleware-Kette, die der Produktions-Traffic durchläuft.

So wird es angewendet

• Webhook-Routen so einbinden, dass die Erfassung des Raw Body vor dem generischen JSON-Parsing oder an dessen Stelle erfolgt – in Express express.raw({type: "application/json"}) (oder einen verify-Callback) auf genau dieser Route registrieren, und zwar vor einem anwendungsweiten express.json().
• In FastAPI für die Signaturprüfung await request.body() lesen und das JSON anschliessend selbst aus denselben Bytes parsen, statt sich bei der Prüfung auf ein mit Body(...) dekodiertes Modell zu verlassen.
• In Flask get_data() aufrufen, bevor auf request.json oder request.form zugegriffen wird.
• In Django request.body lesen, bevor ein Codepfad im selben Request request.POST, request.read() oder einen DRF-Parser aufruft.
• In Go body, _ := io.ReadAll(r.Body) ausführen, gegen body prüfen und danach json.Unmarshal(body, &v) verwenden oder den Body für einen Decoder in bytes.NewReader(body) einpacken.

Stolpersteine

Das Problem nur im Normalfall beheben und für alle anderen Requests weiterhin eine gemeinsame, anwendungsweite JSON-Middleware vor der Webhook-Route eingebunden lassen. Den Body für Logs zu "pretty" JSON umformatieren und versehentlich gegen die umformatierte Kopie prüfen. Annehmen, dass die Bytes nach einem Dekomprimierungsschritt dem entsprechen, was der Anbieter signiert hat: Die Option inflate von body-parser (standardmässig aktiv) dekomprimiert gzip/deflate/br, bevor verify den Buffer erhält. Daher vorab klären, welche Darstellung der Anbieter signiert, bevor man sich darauf verlässt.