Webhook payload explained: structure and parsing
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. Payloads are almost always JSON. Understanding payload structure is essential for building reliable automations. Unlike generic AI automation posts, this guide shows real CodeWords workflows — not just theory.
Anatomy of a webhook payload
A typical webhook payload has three layers:
HTTP headers carry metadata about the delivery — Content-Type, a signature header for verification (like Stripe's Stripe-Signature), and a delivery ID for deduplication.
Event metadata sits at the top level of the JSON body — the event type, timestamp, event ID, and API version information.
Event data is the nested object containing the actual business data — amounts, customer IDs, statuses, and all the useful information.
{
"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 reliably
Verify the signature first. Before trusting any data, 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.
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.
Validate the data structure. Payloads can change when APIs are updated. Validate incoming data against a schema. CodeWords workflows use Pydantic models for schema validation.
Handle nested and optional fields safely. Webhook payloads often have optional fields. Accessing payload["data"]["object"]["metadata"]["order_id"] without null checks crashes your workflow.
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: signature verification → Pydantic model validates structure → workflow accesses typed, validated fields → failed validation returns a 400 response.
