Webhook signatures are commonly described as a security feature added to an endpoint. In practice, they define where the endpoint begins.
A provider signs the original request bytes. If the application verifies a parsed object, re-serialised JSON, altered whitespace, changed key order, or a body whose encoding has been normalised, it is no longer checking the object the provider signed.
The correct boundary
The receiver captures the raw bytes first, reads the signature header, computes the HMAC over those exact bytes, and rejects invalid messages before parsing or routing them.
Only after verification should the system:
- parse the payload;
- identify the provider event;
- apply idempotency;
- persist the inbound record;
- execute forwarding or domain work.
This order matters because parsing is not neutral. Framework middleware can make the body easier to use while quietly destroying the exact representation required for signature checking.
Replay has the same requirement
A useful webhook inspector must preserve the original bytes as well as the parsed representation. The parsed form supports search and inspection. The original bytes support signature analysis and controlled replay.
The system I built keeps capture bounded, returns the original event for duplicate deliveries, and separates replay from first-time processing. Replay is an operator action with its own audit trail, not a disguised new delivery.
Design rule
Treat the raw request body as a cryptographic input, not just transport data. Once transformed, it cannot be reconstructed reliably.