Stripe Webhook

The Stripe webhook is the server-side half of the optional Stripe payments flow. When a shopper completes a Stripe Checkout session, Stripe calls this endpoint; the handler verifies the event, records it as a paid order in Firestore, and best-effort decrements tracked inventory.

Endpoint

POST /api/webhooks/stripe

Defined in src/app/api/webhooks/stripe/route.ts, which pins export const runtime = "nodejs" because firebase-admin, the pg pool, and the Supabase client cannot run on the Edge runtime. The signature covers the raw bytes, so the handler reads await request.text() and never a parsed body.

Only the checkout.session.completed event type is acted on. Every other verified event is acknowledged with 200 and ignored.

What it does

Signature verification

The handler never trusts the request body until Stripe's signature checks out:

const signature = request.headers.get("stripe-signature");
if (!signature) {
  return NextResponse.json({ error: "Missing signature" }, { status: 400 });
}

const payload = await request.text();
let event: Stripe.Event;
try {
  event = stripe.webhooks.constructEvent(payload, signature, webhookSecret);
} catch (error) {
  console.error("Stripe webhook signature verification failed:", error);
  return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}

Recording the order

The route does no database work itself. It converts the verified session into a provider-neutral PaidSession and hands it to the active backend:

const commerce = await getServerCommerce();
const { orderNumber, created } = await commerce.orders.recordPaidSession(
  toPaidSession(session)
);

getServerCommerce() resolves the adapter from COMMERCE_BACKEND, so a Postgres store records the order in Postgres, a Supabase store in Supabase, and a Firebase store in Firestore. recordPaidSession is deliberately absent from the commerce RPC whitelist — it mints a paid order with no payment check of its own, and the only caller allowed to make that claim is this signature-verified route.

export interface PaidSession {
  sessionId: string;                    // idempotency key
  customerId: string | null;            // null for a guest checkout
  customer: { firstName: string; lastName: string; email: string; phone: string };
  items: PaidSessionItem[];             // { id, quantity, variantId? }
  total: number;                        // what the provider charged
}

Idempotency

Stripe retries deliveries, so recording the same session twice must produce one order. Each adapter enforces that with a real constraint rather than a check:

A pre-flight SELECT would not be enough: two deliveries arriving together can both pass it. The constraint is what makes only one win.

Line items from metadata

The purchased lines are not read back from Stripe's line-item API — they are decoded from the session metadata that /api/checkout wrote when creating the session, using decodeItemsMetadata() from src/lib/checkout-metadata.ts.

Each entry is a compact JSON tuple, ["id", quantity] or, for a variant line, ["id", quantity, "variantId"]. Because Stripe caps each metadata value at 500 characters (STRIPE_METADATA_VALUE_LIMIT), long carts spill losslessly across items, items_2, items_3, … keys, which the decoder reassembles in order:

export interface CheckoutItemRef {
  id: string;
  quantity: number;
  variantId?: string;
}

buildPaidOrderItems (src/lib/orders/paid-session.ts, shared by every adapter) then enriches each ref from your catalog with productName, brand, price, subtotal, and primaryImageURL — plus variantId / variantName and the variant-resolved price on variant lines — so the order matches the shape the admin dashboard expects. A product deleted between checkout and delivery degrades to its id with a null price rather than failing the order.

Where it's written

The order is written in two places, mirroring the quote-conversion dual-write:

customerId comes from session.client_reference_id; orderNumber is generated in the form O-YYYYMMDD-NNNNXXXX (e.g. O-20260703-4821K3XW). The order is stored with status: "Processing" and paymentStatus: "paid".

The recorded order looks like:

{
  "orderNumber": "O-20260703-4821K3XW",
  "customerId": "firebase-uid-or-null",
  "customer": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phone": ""
  },
  "items": [
    {
      "id": "prod_123",
      "quantity": 2,
      "productName": "Widget",
      "brand": "Wavecrest",
      "price": 19.99,
      "subtotal": 39.98,
      "primaryImageURL": "https://…"
    }
  ],
  "total": 39.98,
  "status": "Processing",
  "created": "2026-07-03T12:00:00.000Z",
  "paymentStatus": "paid",
  "stripeSessionId": "cs_test_…"
}

The customer name comes from Stripe's single customer_details.name, split into firstName (first token) and lastName (the rest).

Inventory decrement

The stock the order consumed is decremented in the same transaction as the order, so a retried or concurrent delivery cannot oversell:

• Postgres locks every product the session touches with SELECT … FOR UPDATE (ordered by id, so concurrent sessions cannot deadlock) before computing anything, then writes inside one $transaction.
• Firestore reads the products inside runTransaction, so a transaction whose reads were touched concurrently retries and sees the other decrement.

Decrements are grouped per product first (groupStockDecrements) so several lines touching the same product produce a single update, then computeStockUpdate decides what to write. Untracked stock (non-numeric), unknown ids, and unknown variants are skipped silently. Variant lines decrement the variant's own stock when it tracks it, falling back to the product-level stock otherwise — the same math the quote flow uses. See inventory & variants for the shared logic.

Requirements

This endpoint writes with your backend's own server credentials — the ones the commerce layer already needs. Never expose any of them to the client.

On Firebase, provide one of the three credential options; when none is set, getAdminDb() returns null, the webhook logs that the payment completed but the order could not be recorded, and still returns 200. See environment variables for the full list.

Responses

Testing locally with the Stripe CLI

The Stripe CLI forwards live webhook events to your dev server and prints a signing secret to use.

stripe listen --forward-to localhost:3000/api/webhooks/stripe

stripe trigger checkout.session.completed

Related