Webhook payloads explained

July 23, 2026 · 4 min read

The payload is the body of the POST request – the actual news. Every provider structures it differently, but once you know the three common patterns, any payload becomes readable in seconds.

Anatomy of a payload

Almost always JSON, almost always with three ingredients: what happened (event type), what it happened to (the object) and when (timestamp or ID).

{
  "type": "payment_intent.succeeded",   ← event type
  "created": 1690000000,                ← when
  "data": {                             ← the object
    "object": { "id": "pi_3N…", "amount": 4999, "currency": "eur" }
  }
}

The three common patterns

1. Typed envelope (Stripe, Vercel)

A wrapper with type and a nested data object. One endpoint receives all event types; you switch on type. Verbose, but self-describing.

2. Event in the header (GitHub, GitLab)

The body is the object itself; the event type lives in a header like X-GitHub-Event: push. Compact, but you must read headers to know what arrived.

3. Flat object (Shopify, many small tools)

The body is simply the resource – an order, a customer. The event type comes from the header (X-Shopify-Topic) or from the URL you registered per event.

Finding the fields that matter

Don't read the docs first – log one real payload and look at it. Every provider has a “send test event” button, and tools like webhook testing services show the raw body. Then pick out the two or three fields you actually need: an ID for deduplication, an amount, a name.

Things that bite in production

Amounts are usually in cents. 4999 means €49.99 – nearly every payment API does this.
Fields can be missing. Optional fields disappear entirely rather than being null – access defensively.
Payloads grow. Providers add fields without warning; never assume a fixed shape.
Test payloads differ. The “send test” button often produces a skeleton with dummy IDs – don't build on it alone.

Payload → push notification

When a webhook should just reach your phone, the payload question gets small: Webhooky reads title, message, sound and vibrate if present, and otherwise shows the texts you configured for that endpoint – so even a payload you don't control produces a readable notification. Details in the API docs, background in what is a webhook.

Get Webhooky

Free for your first 100 notifications – set up your endpoint in two minutes.