Webhook Payload Design

What a payload should carry

A good webhook payload answers a handful of questions the instant it arrives: what kind of event is this, which resource does it concern, when did it happen, and which specific event is this. Concretely, that means a type, an identifier for the affected resource, a timestamp, and a unique event id that a consumer can use for deduplication later.

{
  "id": "evt_456",
  "type": "resource.updated",
  "created_at": "2026-06-29T04:00:00Z",
  "data": { "resource_id": "res_789" }
}

These core fields let a consumer route the event to the right handler, deduplicate retries, and reason about ordering, all without guesswork. Getting them present and consistent is more important than any amount of extra data piled on top.

Thin or fat payloads

There are two broad styles, and the choice between them shapes everything downstream. A thin payload says only that something happened and gives an id; the consumer then calls the API to fetch the full detail when it needs it. A fat payload includes the resource data inline, saving that follow-up call entirely. Each style buys you something and costs you something else.

Thin payloads keep deliveries small and always reflect current state at the moment the consumer fetches, but they add an API round-trip every time. Fat payloads are self-contained and faster to act on, yet they are larger to transmit and carry a real risk of being stale by the time anyone reads them. The right choice genuinely depends on what the consuming side needs most, so it is worth deciding consciously.

Designing for change

Payloads inevitably evolve as a product grows, so it pays to design them to extend gracefully from the very beginning. Consumers should ignore fields they do not recognise rather than break on them, which is what lets a provider add new fields safely without coordinating a release with everyone at once. Conversely, avoid removing or repurposing existing fields, because doing so breaks anyone who was relying on them.

Treat the payload as a contract with a genuinely long life ahead of it. Additive change — new fields, new event types — is safe and expected; subtractive or breaking change is not. This forward-compatible posture is closely related to event types and schemas, which formalise the exact shape consumers depend on and the rules for evolving it responsibly over time.

Sensitive data and size

Think carefully about precisely what travels inside a payload, because every field you include is a field you must protect. Putting sensitive personal or financial data directly into a delivery widens the set of places where that data is now exposed, logged, and potentially stored. Very often a thin payload carrying just an id is the safer design, letting the consumer fetch any sensitive detail over an authenticated, audited API call instead.

Keep payloads reasonably small in any case, so that they are quick to transmit, easy to log, and cheap to parse at the receiving end. When you are deciding what to include and what to leave out, follow the provider's documented event shapes in the API documentation rather than inventing a structure and hoping it lines up.