Webhook payload

On this page 7

A webhook payload is the body of the HTTP request that a source system sends to a subscriber’s endpoint when a specific event occurs, carrying the data that describes that event. Among the Automation fundamentals, the payload is what turns a bare notification into usable input: it tells the receiving workflow what happened, to which object, and when, so that a trigger can start the right actions without polling.

Most payloads are JSON documents sent with POST, accompanied by headers that identify the event type, the delivery attempt and a cryptographic signature. Designing, validating and parsing payloads correctly is the difference between an integration that runs quietly for years and one that silently drops or duplicates work.

How a webhook payload is delivered

A webhook payload is delivered through a push model: the producer calls the consumer as soon as the event is committed, instead of the consumer asking repeatedly whether anything changed. The subscriber first registers an endpoint URL and the event types it wants, and the producer then serializes the event into a request body and sends it over HTTPS.

The receiver is expected to acknowledge quickly with a 2xx status code, typically within 5 to 30 seconds depending on the provider. If the response is slow, missing or an error, the producer schedules retries with exponential backoff, often over hours or days, and may eventually disable the subscription. Because of this, the receiving side should store the payload and return immediately, leaving heavy processing to a background queue.

The table below shows the parts of a typical delivery and what each one contributes.

ComponentTypical contentPurpose
Request linePOST to the registered URLDelivers the event to the subscriber
Content-Type headerapplication/json or form-encodedTells the parser how to read the body
Event type headerName such as order.createdRoutes the payload to the right handler
Delivery ID headerUnique identifier per deliverySupports deduplication and support cases
Signature headerHMAC digest with timestampProves origin and integrity
BodyJSON object describing the eventCarries the data the workflow consumes
Anatomy of a webhook delivery

Payload structure and common formats

A well-designed payload combines an event envelope with an event-specific data object. The envelope holds metadata that every event shares, such as an event ID, event type, creation timestamp, API version and source, while the data object holds the changed resource or a reference to it.

Providers differ in how much data they include. Fat payloads embed the full resource state, so the consumer can act without further calls. Thin payloads send only identifiers and the event type, and the consumer fetches the current state through the API. Thin payloads reduce exposure of sensitive data and avoid acting on stale snapshots, at the cost of extra requests and rate-limit pressure.

FormatTypical useMain trade-off
JSONMost modern SaaS and developer platformsFlexible but needs schema discipline
Form-encodedOlder payment and messaging servicesSimple, but awkward for nested data
XMLLegacy enterprise and telecom systemsVerbose, strong schema tooling
CloudEvents JSONCloud and event broker ecosystemsStandard envelope, extra fields to learn
Common payload formats and where they appear

The CloudEvents specification defines a vendor-neutral envelope with attributes such as id, source, type, specversion and time. Adopting it lets one receiver handle events from many producers with the same parsing logic, which matters in event-driven automation that spans several platforms.

Security and verification of payloads

A receiver must treat every incoming payload as untrusted until verified, because the endpoint URL is public and anyone who discovers it can post forged events. The dominant protection is an HMAC signature: the producer computes a hash, usually HMAC-SHA256, over the raw body and a timestamp with a shared secret, and the receiver recomputes and compares it.

Verification only works on the exact raw bytes received. Parsing the JSON and re-serializing it before checking the signature changes whitespace or key order and causes false rejections. The comparison should use a constant-time function to avoid timing attacks, and a timestamp tolerance of about five minutes blocks replay of captured requests.

ControlThreat addressedImplementation note
HTTPS onlyEavesdropping and tampering in transitReject plain HTTP endpoints
HMAC signatureForged or altered payloadsVerify raw body before parsing
Timestamp checkReplay of old requestsReject outside a short window
Secret rotationLeaked shared secretAccept two secrets during rotation
Data minimizationExposure of personal dataPrefer thin payloads for sensitive fields
Payload security controls

A webhook payload differs from an API polling response because it is pushed at the moment of change rather than requested on a schedule. It also differs from a message queue message, which sits in a broker with guaranteed retention, whereas a webhook depends on the receiver being reachable when the producer calls.

MechanismLatencyDelivery guaranteeBest fit
Webhook payloadSecondsAt least once, best effortSaaS events feeding workflows
API pollingInterval-boundConsumer controls readsSources without webhooks
Message queueMilliseconds to secondsDurable with acknowledgmentInternal high-volume pipelines
Streaming socketSub-secondOnly while connectedLive dashboards and chat
How webhook payloads compare with alternatives

In practice, many teams land webhook payloads in a queue immediately after verification, combining the low latency of push delivery with the durability of a broker. The payload then feeds a workflow, where conditional branching inspects fields such as status or amount to choose a path.

Common payload handling mistakes

Most webhook failures come from assumptions about delivery that the protocol does not guarantee. Producers send events at least once, may send them out of order, and may change the payload shape between API versions.

  • Ignoring duplicates: without an idempotency check on the event ID, a retried delivery can create a second order, invoice or ticket.
  • Trusting arrival order: an update can arrive before the create event, so handlers should compare timestamps or version numbers before overwriting state.
  • Processing synchronously: long work inside the request handler causes timeouts, which trigger retries and multiply the load.
  • Strict schema parsing: rejecting unknown fields breaks the integration when the provider adds a property; tolerant readers ignore extra fields.
  • Logging full payloads: storing raw bodies with personal or payment data in an execution log creates a compliance liability.

In plain words

Imagine a courier who rings your doorbell the moment a parcel arrives. You no longer need to check the mailbox every hour. The webhook is the doorbell. The payload is the parcel itself. It is a small package of information about what happened, such as a new order with its number and amount.

The receiving system opens the package. It checks that the sender is genuine. Then it starts the next steps on its own. The key idea is simple: the payload is the message, and its contents decide what the automation does next.

A real-world example

An online store selling about 2,000 orders per day connects its payment provider to its fulfillment workflow. Each time a payment succeeds, the provider sends a webhook payload of roughly 3 KB containing the event ID, the event type payment.succeeded, the order reference, the amount and the currency, signed with HMAC-SHA256.

The store’s receiver verifies the signature on the raw body, writes the payload to a queue and returns a 200 status within 150 milliseconds. A worker then checks whether that event ID was already processed, marks the order as paid, reserves stock and notifies the warehouse. During a network incident the provider retried several hundred deliveries, and because of the idempotency check no customer was charged or shipped twice, while every order still reached the warehouse within minutes.