What is a JSON payload?

The pieces JSON is built from

The format is defined in RFC 8259, and it is small enough to learn in one sitting. There are four primitive types, strings, numbers, booleans and null, and two structured types, objects and arrays. An object is an unordered collection of name and value pairs wrapped in braces; an array is an ordered list wrapped in square brackets. Values can nest, so an object can hold arrays of objects as deep as needed. Two rules from the standard catch people out. The names within an object should be unique, and when they are not, different programs behave differently. And JSON exchanged between systems must be encoded as UTF-8, which is why a mangled accented name usually points at an encoding setting rather than at the form.

Payload, headers and envelope

An HTTP request has an address, a set of headers and a body. The payload is the body. Headers describe it, most importantly the content type, which for JSON is application/json, and sometimes a signature proving who sent it. Inside the body, well designed payloads use an envelope: an outer object that says what kind of event this is and when it happened, with the record itself nested one level down. That lets one receiving endpoint handle several event types by reading the outer fields first, and it leaves room to add information later without breaking programs that only read the parts they already know. The word payload itself comes from shipping, where it means the cargo as distinct from the vehicle, and the analogy holds: the headers and the connection exist only to get the body to the right place intact.

A form submission, annotated

Take a demo request form from a fictional software company, Crateline. When somebody submits it, the webhook body is one object. Its event is form_submission, so the receiver knows what happened. Its timestamp records when. Its form object carries the form's id, title and slug, so one endpoint can serve several forms. Its response object carries the response id, then two maps of the same answers. In data, each key is a question label, so Work email points to the address the person typed. In raw_data, each key is the field's internal id, pointing to the same value. The answers are identical; only the keys differ, which is the whole reason both exist.

Reading a payload safely

Parse the body with a JSON parser, never by evaluating it as code and never by searching the raw text for a phrase. Check the event name before acting, then check that each value has the type you expect, because a number can arrive as a string and a checkbox answer can arrive as a list. Treat a missing key and an empty value as the same thing, since different senders represent an unanswered question differently. Do not rely on the order of keys, because the standard defines objects as unordered. Finally, keep a copy of the raw body for anything important, since it is the only record of what was actually received.

Where labels and ids cause trouble

The common failure is an automation built on labels. It works perfectly until somebody fixes a typo in a question, at which point the key changes and the receiving system quietly stops finding the answer. Building on field ids avoids that, at the cost of needing a lookup to know which id is which question. The second failure is two questions with the same label, such as two fields both called Phone. In this form builder's webhook the data map is built by label, so the second answer overwrites the first in data, while raw_data keeps both. Distinct labels solve it before it starts. A useful habit is to keep a small mapping table on the receiving side that pairs each field id with the label it had when the automation was built, so a later rename shows up as a mismatch you can see rather than a value that silently stops arriving.

Questions people ask