What is a webhook payload?
The webhook payload is the body of the HTTP request — usually JSON — describing the event that occurred. A typical payload has three layers: an envelope with delivery metadata (event ID, timestamp, event type), the object the event happened to (a Stripe charge, a GitHub pull request, a Shopify order), and sometimes a `previous_attributes` field showing what changed on update events. Use lenient parsing — payloads grow new fields over time, and strict schemas break on every provider addition. Always store the raw bytes; signature verification depends on byte-for-byte fidelity, never reserialized JSON.
The payload is what the source system sends in the body of the webhook POST. Almost always JSON; rarely form-encoded; almost never XML in modern providers. The payload's shape is part of the contract between source and receiver.
A typical payload has three layers. The envelope carries metadata about the delivery itself — an event ID, a timestamp, an event type string, sometimes a delivery attempt counter. Stripe's envelope, for instance, has id, type, created, and livemode. The object is the thing the event happened to — a Stripe charge, a GitHub pull_request, a Shopify order. The previous_attributes field (when present) tells you what changed if the event is an update.
Two payload pitfalls bite teams hardest. First: payloads grow over time. The Stripe charge object today has dozens more fields than it did in 2018. If your handler validates the payload with a strict schema that rejects unknown fields, every Stripe API addition breaks your integration. Use lenient parsing — pluck the fields you need, ignore the rest, version-pin the API only if you have a real reason.
Second: the payload may not contain everything you need to do your work. Many providers send "thin" webhooks that include only an ID and require a follow-up API call to fetch the full object. GitHub's older webhooks were like this; Stripe's more recent thin-event mode does this on purpose. Your handler must be ready to round-trip back to the source's API for the heavy data, which means it needs API credentials and you need to consider rate limits.
Body size: providers cap payload sizes (Stripe ~256 KB, GitHub ~25 MB for some events). If you proxy or forward webhooks to another system, you must preserve byte-for-byte fidelity — especially raw bytes, not the result of a parse-and-reserialize round-trip — or you will break signature verification downstream.
Always store the raw payload. When something goes wrong at 2am, the only thing that lets you reconstruct what happened is the original bytes the provider sent.
See Webhook Payload in real traffic
WebhookWhisper captures every webhook with full headers, body, signature, and timing — so concepts like webhook payload stop being abstract and become something you can inspect.
Start Free