Skip to Content
Public Beta: Direct engineering support available. Join Discord →
DocsRecipesStripe: Flatten webhook payloads

How do I flatten Stripe webhook payloads?

Time: ~10 minutes | Difficulty: Beginner | Prerequisites: Stripe account with webhook access, Slashbin account

TL;DR: Stripe webhooks arrive as deeply nested envelopes. Instead of writing parsing code, define a Golden Model visually in Slashbin — map the fields you care about, cast currency safely, and your endpoint receives clean flat JSON with the schema you designed.


What You’ll Build

By the end of this guide, your database consumer will receive clean, flat JSON like this — a Postgres-bound service can INSERT it directly, no envelope-walking required:

{ "invoice_id": "in_1MtwBwLkdIwHu7ix4LGN3vfB", "customer_id": "cus_NcTh4G8kxKPeUM", "subscription_id": "sub_1MtwBqLkdIwHu7ixEo1YRZg8", "amount": 49.00, "currency": "usd", "status": "paid", "paid_at": "2023-04-04T18:30:00Z", "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1.../test_YWNjdF8x..." }

Instead of parsing nested data.object.* in your handler, you define the schema once in the model editor and Slashbin extracts, casts, validates, and delivers only the fields your API expects.


The Problem

Stripe events arrive wrapped in an envelope: { id, type, created, data: { object: { ... } } }. The fields you actually need are buried under data.object — and worse, currency amounts come as integer cents in strings that will float-error if you JSON.parse and multiply.

Without a transform layer, your handler is on the hook for:

Without SlashbinWith Slashbin
Walk event.data.object.customer in every handlerMap once visually, receive customer_id at the top level
Convert integer cents ↔ decimal amounts by handSafe decimal casting on currency fields at the gateway
Rewrite handlers when Stripe adds fields you don’t needGolden Model ignores unmapped source fields automatically
Fail silently when a required field arrives nullRequired-field toggles reject invalid payloads before delivery

The Solution

Define a Golden Model in Slashbin’s model editor. Visually map nested Stripe fields to a flat schema, toggle validation on the critical ones, and Slashbin transforms every incoming event before it reaches your endpoint.

Outcome: Your backend receives the exact JSON shape you designed. Bad data is rejected at the gateway, not in your application.


Step 1: Create a Stripe Data Stream in Slashbin

Secure the connection before any data flows.

  1. Data Stream Setup: Click Create New Data Stream and select Stripe.
  2. Type: Choose Transactional — Stripe events are stateful business events.
  3. Security: Paste your Stripe Webhook Signing Secret (starts with whsec_, available in Stripe Dashboard → Workbench → Webhooks → your endpoint → Signing secret).

Result: Slashbin auto-rejects any request that fails Stripe’s HMAC signature check, so only verified Stripe events reach your transform pipeline.


Step 2: Build the Golden Model from Models

Open Models and create a model, or edit an existing one. The raw Stripe event sits on the left (“Source Data”); your clean target schema is on the right.

The Golden Model page describes the canonical, source-shaped schema you define once and validate on every webhook. Transformation Behavior describes what a mapping can do to a string value, including removing a literal leading prefix, and which expression forms a mapping does not support.

Map the Fields You Care About

Use the Field Mappings panel to define the flat JSON your consumer expects:

  • + Add — create a new field mapping. Enter the target field name (e.g., invoice_id) and set its JSONPath source (e.g., $.data.object.id).
  • Pencil icon — edit an existing mapping to change its source path or validation.
  • Add All — import all source fields as-is when you need a full pass-through for debugging.

For an invoice.paid event, the mappings that produce the clean payload above look like this:

Target fieldSource JSONPathNotes
invoice_id$.data.object.idRequired
customer_id$.data.object.customerRequired
subscription_id$.data.object.subscriptionOptional
amount$.data.object.amount_paidDecimal cast — cents → dollars
currency$.data.object.currencyRequired
status$.data.object.statusRequired
paid_at$.createdISO timestamp from Unix seconds
hosted_invoice_url$.data.object.hosted_invoice_urlOptional

Pro tip: Toggle Required ON for invoice_id, customer_id, amount, currency, and status. If any is missing, Slashbin flags the event as invalid instead of forwarding a half-formed row to your database.

Cast Currency Safely

Stripe sends money as integer cents (4900 = $49.00). The model editor supports decimal-safe casting on numeric fields so amount_paid arrives at your endpoint as 49.00, not 4900 or 49.000000001 — no parseFloat traps in your handler.

For fields where the shape depends on the event (e.g., mapping data.object.subscription to a nullable string when Stripe omits it on one-off invoices), use a Derived Mapping to encode the rule declaratively instead of branching in your consumer.

Money has no decimal point, and not every currency has two places

Stripe sends every amount as an integer in the currency’s smallest unit, as in the invoice.paid payload from the Before & After section below:

{ "amount_paid": 4900, "currency": "usd" }

4900 is 4,900 cents, so $49.00. The scale depends on the currency. Stripe documents zero-decimal currencies  such as JPY, where 4900 means 4,900 yen, and three-decimal currencies  such as BHD, where 4900 means 4.900 dinars.

A handler that divides every amount by 100 is right for USD and wrong by a factor of 100 for JPY. It does not error. It records a plausible but wrong number.

The cents-to-dollars mapping in the table above is written for two-decimal currencies like USD. Keep currency mapped and Required, as in the table, so every record you receive says which scale its amount belongs to. This recipe makes no claim about how a mapping handles other scales, so check the value your consumer receives for a zero-decimal currency before you rely on it.

When you are ready to reshape more of the event, the Golden Model page covers the validation and derived-field surface.


Step 3: Publish the Model

Before Slashbin transforms live events, publish the model.

Click Publish in the top navigation to activate it. The version number increments on each publish.

Safe by default: Unpublished models don’t drop events. Incoming Stripe webhooks are captured in the Dead Letter Queue until a matching model is live, so nothing is lost while you iterate.


Step 4: Deliver the Clean Payload to Your Destination

On the Outbound tab, click + Add Destination and choose Custom Webhook.

  1. Enter a Name (e.g., “Postgres Ingest”).
  2. Enter your URL (e.g., https://api.example.com/webhooks/stripe-invoices).
  3. Add any headers your endpoint requires, then click Add Destination.

The Developer Guide tab shows the exact JSON your endpoint will receive plus signature-verified receiver code in multiple languages. Your handler now inserts a single flat row per event — no envelope walking:

// Express — consume the transformed payload directly. import express from 'express' const app = express() app.post('/webhooks/stripe-invoices', express.json(), async (req, res) => { const invoice = req.body // already flat: { invoice_id, customer_id, amount, ... } await db.query( `INSERT INTO invoices (invoice_id, customer_id, subscription_id, amount, currency, status, paid_at) VALUES ($1, $2, $3, $4, $5, $6, $7) ON CONFLICT (invoice_id) DO UPDATE SET status = EXCLUDED.status, amount = EXCLUDED.amount`, [ invoice.invoice_id, invoice.customer_id, invoice.subscription_id, invoice.amount, invoice.currency, invoice.status, invoice.paid_at, ], ) res.status(200).end() })

Copy the Ingestion URL from the Slashbin dashboard and paste it into Stripe Dashboard → Workbench → Webhooks. Select the event types you want transformed (e.g., invoice.paid, invoice.payment_failed, checkout.session.completed).

Done. Stripe posts to Slashbin, the Golden Model transforms every event, and your endpoint receives clean flat JSON on every delivery.


Before & After

What Stripe Sends (nested envelope):

{ "id": "evt_1MtwBwLkdIwHu7ixV1YrJ8vN", "object": "event", "type": "invoice.paid", "created": 1680640200, "data": { "object": { "id": "in_1MtwBwLkdIwHu7ix4LGN3vfB", "object": "invoice", "customer": "cus_NcTh4G8kxKPeUM", "subscription": "sub_1MtwBqLkdIwHu7ixEo1YRZg8", "amount_paid": 4900, "amount_due": 4900, "currency": "usd", "status": "paid", "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1.../test_YWNjdF8x...", "lines": { "data": [ /* nested line items */ ] }, "...": "60+ more fields (period, discounts, tax, metadata, etc.)" } } }

What Your API Receives (Golden Model):

{ "invoice_id": "in_1MtwBwLkdIwHu7ix4LGN3vfB", "customer_id": "cus_NcTh4G8kxKPeUM", "subscription_id": "sub_1MtwBqLkdIwHu7ixEo1YRZg8", "amount": 49.00, "currency": "usd", "status": "paid", "paid_at": "2023-04-04T18:30:00Z", "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1.../test_YWNjdF8x..." }

Why Slashbin vs a Raw Handler

  • Schema enforced once, not per handler. Golden Model defines the shape at the gateway. Every downstream service sees the same JSON.
  • Decimal-safe currency casting. Cents → dollars is a mapping property, not a parseFloat you have to remember in every language.
  • No parsing code to maintain. When Stripe adds a field, your handler doesn’t change — the model already ignores unmapped source fields.
  • Retries and replay for free. Because the transform runs at the gateway, retries and replay operate on the original raw payload — you can re-run any event through the latest model without touching Stripe.

Next Steps