Webhook payload explained

A webhook payload is the data packet sent by a service when an event occurs. When Stripe processes a payment, GitHub receives a push, or a form gets submitted, the source service makes an HTTP POST request to your specified URL. The body of that POST request — the payload — contains all the details about the event: what happened, when, to whom, and the relevant data.

Payloads are almost always JSON, though some legacy services use XML or form-encoded data. The structure varies by service, but the pattern is consistent: metadata about the event plus the event data itself. Understanding payload structure is essential for building reliable automations. Unlike generic AI automation posts, this guide shows real CodeWords workflows — not just theory.

According to RapidAPI's 2025 State of APIs report, 83% of API-first companies use webhooks for real-time event delivery. The HTTP specification defines the transport layer, while payload structure is service-specific — every API designs its own format.

Related: event-driven architecture explained, API authentication methods explained, Sentry webhook, Slack API events, what is an automation trigger, CodeWords integrations, CodeWords templates.

Anatomy of a webhook payload

A typical webhook payload has three layers.

HTTP headers carry metadata about the delivery. Key headers include Content-Type (usually application/json), a signature header for verification (like Stripe's Stripe-Signature or GitHub's X-Hub-Signature-256), and sometimes a delivery ID for deduplication. Headers arrive before the body and tell your receiver how to parse and verify the payload.

Event metadata sits at the top level of the JSON body. This includes the event type (payment_intent.succeeded, push, form_submission), a timestamp, an event ID, and sometimes API version information. This metadata tells your workflow what happened without parsing the full payload.

Event data is the nested object containing the actual business data. For a Stripe payment event, this includes the amount, currency, customer ID, payment method, and status. For a GitHub push, it includes the commits, branch, repository, and author. This is where the useful information lives.

Example Stripe webhook payload (simplified):

{
  "id": "evt_1abc123",
  "type": "payment_intent.succeeded",
  "created": 1716825600,
  "data": {
    "object": {
      "id": "pi_xyz789",
      "amount": 2000,
      "currency": "usd",
      "customer": "cus_abc456",
      "status": "succeeded"
    }
  }
}

Parsing payloads in automation workflows

Reliable payload parsing follows a consistent pattern.

Verify the signature first. Before trusting any data in the payload, verify that it actually came from the claimed source. Most services include an HMAC signature computed from the raw payload body and a shared secret. CodeWords handles signature verification automatically for its native integrations. For custom webhooks, Cody generates the verification code as part of the workflow.

Extract the event type. Use the event type field to determine which handler should process the payload. A single webhook endpoint often receives multiple event types — payment succeeded, payment failed, subscription canceled. Your workflow branches based on this field.

Validate the data structure. Payloads can change when APIs are updated. Validate incoming data against a schema before processing. CodeWords workflows use Pydantic models for schema validation — if a field is missing or has the wrong type, the validation catches it before downstream steps run.

Handle nested and optional fields safely. Webhook payloads are notorious for optional fields that appear in some events and not others. A payment event might include metadata only if the customer set it. Accessing payload["data"]["object"]["metadata"]["order_id"] without null checks crashes your workflow. Defensive parsing is essential.

Common payload formats across services

Different services structure payloads differently.

Stripe wraps everything in a data.object structure with a clear type field. Well-documented, versioned, consistent.

GitHub uses a flat structure with event-specific fields. The event type comes from the X-GitHub-Event header, not the payload body.

Slack sends different payload formats for different features — Events API, Interactive Components, and Slash Commands all have different structures. This inconsistency is a common source of webhook parsing bugs.

Sentry includes the full error context — stacktrace, breadcrumbs, tags — which can make payloads very large. Budget for payload size limits on your receiving endpoint.

Webhook payloads in CodeWords workflows

CodeWords workflows receive webhook payloads as FastAPI request bodies. The generated Python code includes type-safe payload parsing with automatic validation. A typical pattern:

1. Webhook arrives at a CodeWords-generated endpoint.
2. Signature verification runs automatically.
3. Pydantic model validates the payload structure.
4. The workflow logic accesses typed, validated fields.
5. Failed validation returns a 400 response — the sender knows to retry.

This pattern works across the 500+ integrations CodeWords supports. For services that send unusual formats, Cody generates custom parsers. Platforms like Zapier, Make, and n8n abstract payload parsing behind their connector layers — convenient but harder to debug when something goes wrong.

Debugging webhook payloads

When a webhook-triggered workflow fails, the payload is your first clue. Log the raw payload body before processing. Use tools like RequestBin or ngrok's inspector to capture and examine payloads during development. Check for encoding issues, unexpected null values, and API version mismatches.

CodeWords logs full execution details including incoming payloads, making post-mortem debugging straightforward. Start building webhook-driven workflows at codewords.agemo.ai using ready-made templates.