Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Webhooks and APIs

Webhook Payloads, Nested Data and Line Items

Understand how nested JSON, arrays and line items appear in Zapier steps, why keys use double underscores, and how to flatten and loop over data safely.

A webhook payload is rarely a flat list of fields. Real systems send objects inside objects (a customer with an address) and lists (an order with many items). Zapier has to show all of that in a field picker, and your job is to understand what the picker is really showing you. This lesson covers JSON in the form Zapier cares about, how nested keys are presented, and what happens to arrays, the biggest source of surprise for beginners.

The product cannot run here, so the code below is our own JavaScript stand-in that imitates the flattening idea. It is not Zapier's code, and Zapier's exact field naming can differ slightly between triggers, so always read the field names in your own editor.

JSON in two minutes

JSON has six kinds of value: text ("Ada"), numbers (49.5), booleans (true), null, objects ({ "a": 1 }) and arrays ([1, 2, 3]). A typical order event:

JSON
{
  "event": "order.paid",
  "order_id": 1042,
  "customer": { "name": "Ada Lovelace", "email": "[email protected]" },
  "items": [
    { "sku": "TEA-01", "qty": 2, "price": 4.5 },
    { "sku": "MUG-07", "qty": 1, "price": 12 }
  ],
  "paid": true
}

Everything Zapier shows you comes from a structure like this. Text fields are strings even if they look like numbers: a form-encoded qty=2 arrives as the text "2", which matters when you do maths (the Formatter's Numbers actions convert text to numbers).

How nesting is shown

The field picker is a flat list, so Zapier joins the path of a nested key with double underscores. In the example above you would pick fields such as customer__name and customer__email. Use the picker rather than typing names yourself, because a wrong separator gives an empty value without an error.

Arrays are different. Items of an array are shown as line items: each field of the item becomes a list of values that line up by position. So items__sku is the list TEA-01, MUG-07, items__qty is 2, 1. If you drop items__sku into a text field, you typically get the values joined with commas, which is fine for an email but useless if you need one row per item.

The stand-in below flattens nested objects with double underscores and turns arrays of objects into parallel lists, like the picker does.

JS Stand-in: flatten a payload the Zapier way

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The result has customer__email as a single value and items__sku as a two-element list. That list shape is the heart of this lesson.

The line-item problem

Suppose you want to add one spreadsheet row per ordered item. Zapier's normal actions run once per trigger, so they would create a single row with TEA-01, MUG-07 in one cell. There are three common solutions:

  1. Looping by Zapier. Takes line items and runs the following actions once per item. Each pass counts toward your task usage (see Task Usage and Cost Control).
  2. Send the items individually. If you control the sender, post one event per item, or send an array of events in separate requests.
  3. Join and keep as text. For notifications, a comma-joined list is often enough, and costs nothing extra.

A Code step or the Formatter's Line-item to Text and Text to Line-item actions help convert between the two shapes. Use Utilities > Line-item to Text when a human will read the result.

JS Stand-in: one row per line item

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Two cautions about this approach. First, parallel lists assume every list has the same length; if one field is missing for an item, positions shift and values end up on the wrong row. Second, qty and price arrive as text, so convert before calculating.

Picking a child key

When creating a Catch Hook you can type a Pick off a Child Key. If your payload is { "data": { ...the real event... } }, enter data and Zapier will treat the content of data as the event, so fields appear as email instead of data__email. It also lets you accept a payload where the event is the first item of a list: use the child key that selects it. Only one key is allowed, so for a deeper structure you reshape with a Code step.

Empty, missing and odd values

Situation What you may see How to handle it
Key missing in a later request Field empty in the step Filter or default with Formatter "Default Value"
null Empty value Same as above
Number sent as text "007", "2" Convert with Formatter Numbers, keep ids as text
Date in a local format 14/03/2026 Formatter Date/Time with the right "from" format
Boolean true or false as text Filter with "(Text) Exactly matches" true

Keep ids as text. Converting 007 to a number silently turns it into 7, and big ids can lose precision. Only convert quantities and money.

Designing payloads for easy automation

If you control the sender, make life easy for the Zap: one event per request, an event name (order.paid), the main id, flat fields for the values people filter on, and arrays only for true lists. Add a version field ("v": 2) so you can handle a change in shape without breaking running Zaps. This pairs with the naming ideas in Naming, Documentation and Change Management.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How does the Zapier field picker usually show the email inside a customer object?

    Nested keys are joined with double underscores in the picker. Always select the field from the picker instead of typing it.
  2. 2. An order has three items. What happens if you map items__sku into a single Create Row action without Looping?

    Actions run once per trigger, so the line items arrive as one joined value. Use Looping or send one event per item to get one row per item.
  3. 3. Why keep ids like 007 as text?

    Ids are labels, not quantities. Number conversion can change them.

Summary

  • Nested JSON keys appear joined with __; arrays of objects appear as line items (parallel lists).
  • Use Looping, separate events, or a joined text depending on whether you need one row per item.
  • Form data and many APIs deliver numbers as text: convert before maths, never convert ids.
  • Pick off a child key to skip a wrapper object.
  • Design payloads on purpose: one event, flat key fields, an id, a version.

Next: Sending Requests with Webhook Actions