On this page

The Same JSON Value Can Have Different Signed Bytes
JSON formatting can break webhook signature verification when the signature authenticates the original request-body bytes. Adding a space, rewriting a character escape, or serializing a parsed object changes that input even when the decoded JSON value stays identical. The reliable receiving order is: capture the original body, verify it according to the provider’s complete signing rules, and only then parse or format it for processing.
The distinction matters most when debugging an integration that receives sensible-looking JSON but rejects its signature. Comparing parsed values answers whether the data agrees; comparing the preserved signing input answers whether verification received the expected representation. The examples below make that difference visible without assuming that every webhook provider signs the same way.
Consider two JSON representations:
{"a":1}
{"a": 1}
Both represent an object whose a value is 1; the second adds a space after the colon. For these UTF-8 examples the first body contains seven bytes and the second contains eight.
| Comparison | Result |
|---|---|
| Parsed JSON values | Equal |
| Original body bytes | Different |
| Suitable substitutes for raw-body verification | Do not assume so |
When a signing procedure includes the original body, that space is part of the representation being authenticated. A verifier cannot substitute a visually similar body merely because both versions parse to the same value. This gives debugging a concrete starting point: matching objects do not establish matching signing inputs. If verification fails after formatting, compare the preserved body with the bytes actually passed to verification — a successful parse does not resolve that comparison, and re-compacting the JSON does not establish that the original representation was restored.
Formatting and Escaping Change the Signing Input
Formatting involves several independent choices, and each deserves its own inspection — a broad label like “JSON cleanup” can hide the exact transformation responsible for a mismatch:
| Transformation | What to inspect |
|---|---|
| Whitespace | Were spaces or indentation added or removed? |
| Property order | Did serialization write properties in a different order? |
| Line endings | Were line breaks added, removed, or rewritten? |
| Character escaping | Did literal characters become escape sequences, or the reverse? |
| Character encoding | Was the body converted into a different encoding? |
Escaped versus literal characters. Compare {"text":"é"} with {"text":"\u00e9"}. Both decode to the same string value, but their UTF-8 body representations differ: one writes the character directly, the other its JSON escape sequence. A formatter or serializer switching between these representations changes the potential signing input — and the decoded text can still look identical in an application interface, which is why a byte comparison beats a visual comparison here.
Readability and verification serve different purposes. Indentation makes a payload easier to inspect; reordering properties can make a displayed object easier to compare. Those operations belong on an inspection copy whenever verification depends on the original body. Character encoding deserves an even sharper check: if a processing step converts the body to another encoding, the original signature can become invalid outright. Follow the provider’s encoding requirements instead of assuming any representation of the same text is interchangeable.
Parsing a Copy Does Not Replace the Original Body
Retaining the original bytes and parsing a separate copy is fundamentally different from reconstructing the request body from a parsed object. In the first approach, the verification input remains available; in the second, verification receives a newly serialized representation that may differ from the delivery. The distinction is about which value reaches the verifier — not whether parsing happens anywhere in the application:
| Approach | Input supplied to verification |
|---|---|
| Preserve the body and parse a separate copy | The preserved original body |
| Parse, then serialize the resulting object | A reconstructed body whose representation may differ |
A parsed object does not preserve every detail of the text that produced it. It does not record whether a space followed a colon, or whether a character appeared literally or through an escape sequence. Serializing that object therefore cannot be assumed to recover the original body:
// the information that matters to the signature is gone after parse:
const body = '{"a":1,"text":"é"}';
const obj = JSON.parse(body);
JSON.stringify(obj); // '{"a":1,"text":"é"}' — this time it matches…
JSON.parse('{"a": 1}') && JSON.stringify({a:1}); // '{"a":1}' — …but nothing guarantees it
// parse is lossy for *representation*: spacing, escapes, key order all unrecorded
When reviewing an implementation, trace the variable passed into verification. Does it still contain the captured body bytes, or was it replaced with the output of a serializer? Keeping the original body under a distinct variable name makes this boundary much easier to review — and easy to see when someone later reassigns it.
Capture the Body, Verify It, Then Transform It
Organize the receiving path so verification has access to its required input before formatting or reconstruction can replace it. Four steps, in order:
- Capture the original request body before middleware transforms the representation needed by the provider’s signing procedure.
- Preserve the required signature headers and metadata — the body may be only one component of the signed input.
- Verify using the provider’s library or documented procedure, supplying the preserved body and every other required component in the specified form.
- Stop event processing if verification fails. A readable payload or successful JSON parse never stands in for authentication. Parse and transform only after successful verification, using the verified delivery for application processing and a separate formatted copy for inspection.
The application’s capture point deserves an explicit check. A request handler receiving an already-parsed object does not demonstrate that the original body remains available — inspect the framework’s body-capture mechanism and the middleware order rather than assuming that serializing the object recovers the incoming representation. Keep business actions behind successful verification; that makes the receive-to-process sequence legible: preserve the input, authenticate the delivery, then interpret its contents.
// Express-shaped sketch of the ordering:
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verify(req.body, req.headers['x-signature']); // raw bytes in
if (!ok) return res.status(400).end(); // stop before any parse
const data = JSON.parse(req.body); // verified — now parse
process(data);
});
Follow the Provider’s Complete Signing Format
Preserving the body is necessary for a raw-body signing procedure, but it may not be sufficient. Webhook signing formats can include metadata as well as the request body, and verification must follow the complete format used by the integration. A body-only procedure and a timestamp-plus-body procedure require different inputs: in the latter, having the correct body does not compensate for a missing timestamp, incorrect component ordering, or an incorrect way of joining them. Resolve these requirements from the provider’s documentation rather than inferring them from an unrelated example:
| Requirement | Question to resolve |
|---|---|
| Signed components | Which body bytes, headers, or metadata are included? |
| Ordering and encoding | In what order and representation are those components combined? |
| Signature header | How must the received header be interpreted? |
| Algorithm | Which algorithm does this integration require? |
| Digest encoding | How is the signature represented for comparison? |
| Secret interpretation | How must the configured secret be supplied to verification? |
| Replay checks | What authenticated freshness information or delivery identifier is available? |
One item on that table trips teams more than the rest: secret interpretation. Some providers expect the raw secret bytes, others a base64 decode of the configured string. Supplying the wrong form to the MAC function produces a verifier that rejects every delivery — including perfectly formed ones — and the symptom looks identical to a body-transformation bug. Confirm it before suspecting the bytes.
A Valid Signature Does Not Prevent Repeated Processing
A captured delivery can retain its valid signature when replayed. Signature verification alone therefore does not prevent the same delivery from being processed twice. Where the protocol authenticates a timestamp, apply its documented freshness checks; if the integration provides an event identifier, determine how it should support duplicate-processing controls — typically a short-lived store of recently seen identifiers checked before business processing begins.
Establish these rules from the provider’s procedure and the application’s own processing requirements. Do not invent a universal acceptance window, and do not assume every protocol includes the same fields. The freshness check and the idempotency check answer different questions — is this delivery recent? versus have I handled this event already? — and an integration that passes one can still fail the other:
// two independent gates, both required:
const fresh = Math.abs(now - timestamp) <= tolerance; // freshness, from protocol
const seen = processedIds.has(eventId); // idempotency, from your app
if (!fresh || seen) return res.status(200).end(); // acknowledge, don't reprocess
processedIds.add(eventId);
Demonstrate the Mismatch, Then Trace the Boundary
This executable Python fixture isolates the effect of parsing and serialization. It uses a synthetic body-only HMAC calculation; it is not a complete verifier for any particular provider:
import hmac, json
a = b'{"a":1}'
b = json.dumps(json.loads(a)).encode()
mac = lambda x: hmac.digest(b'demo-only', x, 'sha256')
print(json.loads(a) == json.loads(b), a == b, mac(a) == mac(b))
Expected output:
True False False
Read the three results in order. True: both bodies parse to the same JSON value. False: the original body and the serialized body contain different bytes. False: the HMAC results for those two inputs differ. Here serialization produced b'{"a": 1}', adding the space after the colon; the fixture keeps the secret and algorithm fixed, so the changed body representation is the only variable being demonstrated. Use it to test the value-equality versus byte-equality distinction before investigating a larger receiving pipeline. The literal demo-only is fixture data — a real integration must supply its own required secret interpretation, algorithm, signed components, header handling, and replay checks, and substituting a real secret into this example would not establish that any of those were implemented correctly.
Finding the first transformation that caused the mismatch. Use synthetic payloads to trace the body through the receiving pipeline. At each relevant boundary, compare the preserved input with the representation about to enter the next step. Record byte lengths and locate the first differing byte rather than relying on formatted displays. In the fixture, the original body has seven bytes and the serialized body has eight; their first difference is at zero-based offset 5, where the original has 1 and the serialized version has a space — the inserted whitespace, identified directly. Equal lengths would still require a byte comparison, because a representation can change without becoming longer.
Inspecting the transformation boundary. Work through the path in order: check where the body is captured relative to JSON parsing and other middleware; inspect whether a proxy or middleware step transforms the body before capture; compare the captured body with the exact bytes supplied to verification; then check encoding conversions, escaping changes, property ordering, and newline handling at the first point of difference. If the body remains identical, move on to additional signed components, signature decoding, algorithm selection, and secret selection. Keep the formatter on a separate inspection copy throughout — it can reveal the payload's structure while the preserved body remains the input used for verification. The final check is concrete: can the synthetic delivery reach verification with its original body intact, and does the verifier receive every other component the provider requires? Once those boundaries are explicit, a signature mismatch has a small, testable set of causes instead of a vague cloud of "webhook problems".