Buffer Stripe Webhooks

Overview

Stripe sends one webhook per event: charges, invoices, subscription changes and more. With Webbu you can batch the events of each Stripe customer and process them together.

Setup

1. Create a buffer

curl -X POST https://webbu.dev/api/v1/admin/buffers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $WEBBU_API_KEY" \
  -d '{
    "bufferId": "b_stripe",
    "projectId": "p_shop",
    "name": "Stripe events",
    "groupKey": { "mode": "jsonpath", "path": "$.data.object.customer" },
    "batch": { "maxItems": 50, "maxBytes": 262144, "idleTimeoutMs": 10000, "maxWaitFromFirstMs": 60000 },
    "delivery": { "url": "https://your-app.example.com/webhooks/stripe-batch" }
  }'

$.data.object.customer is the customer ID on invoice, charge, payment intent and subscription events.

Events whose object has no customer field (for example customer.created, where the customer ID is data.object.id, or product.* events) are rejected with 400 because no group key is found, and Stripe will keep retrying them. Subscribe the endpoint only to events that carry data.object.customer, or use a second buffer grouped by another field, such as $.type, for the rest.

2. Configure Stripe

In the Stripe Dashboard:

Add an endpoint
Set the URL to https://webbu.dev/api/v1/ingest/p_shop/b_stripe
Select the events you want
Save

3. Process batches

Your endpoint receives the events of one customer per request:

{
  "webbu": { "bufferId": "b_stripe", "groupKey": "cus_ABC123", "segment": 0, "…": "…" },
  "window": { "firstItemAt": 1767225600000, "lastActivityAt": 1767225605000, "itemsCount": 2 },
  "items": [
    { "messageId": "…", "receivedAt": 1767225600000, "payload": { "id": "evt_1", "type": "invoice.paid", "data": { "object": { "customer": "cus_ABC123", "amount_paid": 2999 } } } },
    { "messageId": "…", "receivedAt": 1767225605000, "payload": { "id": "evt_2", "type": "charge.succeeded", "data": { "object": { "customer": "cus_ABC123", "amount": 2999 } } } }
  ]
}

Things to know

Signatures: Webbu forwards the parsed events, not Stripe's original requests, so the Stripe-Signature header can't be verified at your endpoint. If you need to trust event contents, fetch each event from the Stripe API by payload.id.
Duplicates: Stripe may send the same event more than once. Deduplicate by the event ID (payload.id).
Credits: each Stripe event uses 1 credit per started KB; most events are a few KB.