Viewing webhook payloads: JSON, forms, XML and binary
By the HookWatcher team · Updated
Formats you'll see
| Content-Type | Typical senders | How to read it |
|---|---|---|
application/json | Stripe, GitHub, Shopify, Razorpay, most modern APIs | JSON tree; copy paths to fields |
application/x-www-form-urlencoded | Twilio, Slack slash commands and interactivity, HTML forms | Key/value pairs; values may contain JSON |
multipart/form-data | File uploads, email-to-webhook services | Named parts, each with its own headers |
application/xml, text/xml | Older payment gateways, SOAP-style callbacks | Text; never resolve external entities |
application/octet-stream | Binary exports, protobuf | Hex view; decode with the sender's schema |
HookWatcher stores every body byte for byte and shows it in the matching view: a JSON tree, form fields, multipart parts or highlighted XML. Binary bodies are kept byte for byte, with a hex view in the replay tools. The original bytes are what forwarding and replay send.
Try it: send each payload format
Live, on a real endpointJSON
Most providers wrap the interesting object in an envelope. Knowing the envelope tells you where to look and which ID to deduplicate on:
{
"id": "evt_1042",
"type": "payment_intent.succeeded",
"created": 1763190000,
"data": {
"object": {
"id": "pi_3QabC",
"amount_received": 4999,
"currency": "usd",
"metadata": { "order_id": "ord_1042" }
}
}
}In a JSON tree you can copy a field's path, such as data.object.metadata.order_id, straight into your handler or a test assertion. To format, validate or minify a payload outside HookWatcher, use the JSON formatter; to compare two deliveries, the JSON diff.
Form-encoded bodies
Form bodies are key=value pairs joined with &, with spaces as + and other characters percent-encoded. Twilio sends its webhook parameters this way. Slack's interactive components send a single payload field whose value is JSON, so you parse twice:
payload={"type":"block_actions","user":{"id":"U012A"},"actions":[{"action_id":"approve","value":"ord_1042"}]}// raw: the request body as a string, before any parsing
const params = new URLSearchParams(raw);
const payload = JSON.parse(params.get("payload"));
console.log(payload.actions[0].value); // "ord_1042"The URL decoder splits a form body into its parameters if you want to read one by hand.
Multipart
A multipart body is a list of parts separated by a boundary string declared in the Content-Type header. Each part has its own headers (Content-Disposition with a name and, for files, a filename) and its own body:
Content-Type: multipart/form-data; boundary=----hw42 ------hw42 Content-Disposition: form-data; name="note" invoice for March ------hw42 Content-Disposition: form-data; name="file"; filename="invoice.pdf" Content-Type: application/pdf %PDF-1.7 …binary… ------hw42--
Never split multipart bodies by hand in production code: the boundary parameter may be quoted, part bodies can contain CRLF, and line endings must be CRLF. Use your framework's parser and set a maximum size.
XML
Read XML payloads as text, and configure your parser to refuse external entities and DTDs. An XML body that defines entities pointing at local files or internal URLs (an XXE attack) is a real risk for public webhook endpoints. HookWatcher shows XML as escaped, highlighted text and never resolves entities.
Compressed and binary bodies
Content-Encoding: gzip
Some senders compress large payloads. The bytes on the wire are gzip, not JSON, and the Content-Encoding header says so. Decompress before parsing. Many servers do this automatically, which matters for signatures: check whether the provider signed the compressed or the decompressed bytes.
Binary
A hex view shows binary bodies without mangling them. If a "JSON" body shows up as unreadable characters, look at Content-Encoding first: it's usually compression, not corruption.
Parsing pitfalls that corrupt payloads
- Large integers. JavaScript's
JSON.parseturns9007199254740993into9007199254740992: numbers above 2⁵³ lose precision. Providers that use 64-bit numeric IDs often send a string version too (such asid_str); use it, or a parser that keeps big integers. - Money as floats. Stripe and Razorpay send amounts as integers in the smallest currency unit (
4999= 49.99). Don't divide and store floats. - Character encoding. Decode as UTF-8 unless the Content-Type says otherwise. Mis-decoded text shows up as
éinstead ofé. - Re-serializing before verifying. Parsing and then
JSON.stringify-ing changes the bytes and breaks HMAC verification. See signature mismatches. - Assuming fields exist. Nested objects are often absent for some event types. Read optional fields defensively and test with real payloads.
See your payload exactly as it was sent
Frequently asked questions
Why is my JSON payload shown as text?
The Content-Type probably isn't application/json (or a +json type), or the body isn't valid UTF-8 JSON. Check the header first: some senders label JSON as text/plain.
How do I view a payload that's Base64-encoded inside JSON?
Copy the field's value into the Base64 decoder. Text is shown as text; binary results (digests, images) as hex.
Do formatting and masking change the stored request?
No. In HookWatcher, formatting and masking are views. The stored bytes are never modified, and replay sends the original.