What is inside a webhook message

A webhook message has two main parts. The headers describe the message. The body carries the data. The event name, which says what happened, can sit in either.

What you need

• A saved sample message from your tool, ideally from its test or "catch" screen.
• A willingness to read labelled lists. Nothing here needs coding.

Headers: the details on the outside

MDN defines HTTP headers as a way for the sender and receiver to pass extra information along with a message.¹ Think of the writing on an envelope.

Some headers are common to all web traffic. The Content-Type header indicates the media type of what's being sent.¹ A webhook that sends JSON will usually say so there.

Others are the sender's own. GitHub says the event type can be found in its X-GitHub-Event request header.² It also has an X-GitHub-Delivery header, which lets a receiver tell each delivery apart.²

Stripe puts a signature in a header called Stripe-Signature.³ Stripe uses it, with a secret, to let the receiver verify the request really came from Stripe.³ Think of it as a seal.

The body: the data itself

The body is usually written in JSON. MDN calls JSON a text-based data format that follows JavaScript object syntax.⁴ You don't need to know JavaScript to read it.

Here's a made-up example of a form message. It isn't from any real tool.

{
  "event": "form.submitted",
  "form": "contact",
  "fields": {
    "name": "Sam Example",
    "message": "Do you do weekend bookings?"
  }
}

Read it as labels and values. Labels on the left. Values on the right. After you've read a couple of real messages from your own tools, the pattern sticks, and the longer ones stop looking strange. MDN notes that property names must be string literals enclosed in double quotes.⁴

Curly brackets wrap a group of labels. Square brackets wrap a list. A group can sit inside another group, as "fields" does above.

The event name

The event name says what happened. Where it lives depends on the sender. In the example, it's a field called "event" in the body. In GitHub's case, it's in a header.²

Stripe says its webhook requests carry a JSON payload that includes event information.³ So for Stripe, the body holds it.

Read the sender's own documentation. There isn't one fixed place for the event name.

How automation tools show it

Zapier's Catch Hook trigger parses the request body.⁵ Its Catch Raw Hook trigger leaves the body unparsed, includes the headers, and has a size limit.⁵ If you need headers, pick the raw one.

Parsed means the tool has split the JSON into separate fields. You can pick from them in later steps. No typing.

Checking what you got

Always start from a real sample. Don't guess. Read one message from top to bottom, because the field names and the event name are right there in front of you, spelled out exactly as the sender writes them.

• Send a test event from the sending app.
• Open the test or history screen in the receiving tool.
• Look for the event name, then the fields you plan to use.
• Note any field that holds personal details. You'll want to decide what happens to it. See passing webhook data to an AI step.

If nothing shows up, check the address first. The webhook URL page explains the usual mix-ups.