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. The route is marked export const dynamic = "force-dynamic" because the raw request body must be read per request for signature verification — it must not be cached or pre-parsed.

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

recordOrder() mirrors the quote → order conversion (dbService.createOrderFromQuote) using the Firebase Admin SDK.

Idempotency

Stripe retries deliveries, so the handler first checks whether an order already exists for this session id and returns early if so:

const existing = await adminDb
  .collection("orders")
  .where("stripeSessionId", "==", session.id)
  .limit(1)
  .get();
if (!existing.empty) return;

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;
}

For each decoded ref the handler reads the catalog document from the products collection to enrich the line with productName, brand, price, subtotal, and primaryImageURL (and, for variant lines, variantId / variantName with the variant-resolved price) so the order matches the shape the admin dashboard expects.

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-NNNN (e.g. O-20260703-4821). The order is stored with status: "Processing" and paymentStatus: "paid".

The recorded order document looks like:

{
  "orderNumber": "O-20260703-4821",
  "customerId": "firebase-uid-or-null",
  "customer": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phone": ""
  },
  "items": [
    {
      "id": "prod_123",
      "quantity": 2,
      "productName": "Widget",
      "brand": "Acme",
      "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

After the order is saved, tracked stock is decremented best-effort: it is wrapped in try/catch and any failure is logged but never fails the already-recorded order.

try {
  const groups = groupStockDecrements(itemRefs);
  const batch = adminDb.batch();
  // …read each product, computeStockUpdate(), batch.update()…
  if (hasStockUpdates) await batch.commit();
} catch (error) {
  console.error(`Failed to decrement stock for order ${orderNumber}:`, error);
}

Decrements are grouped per product first (groupStockDecrements) so several lines touching the same product document produce a single batched 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

Provide one of the three Firebase 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