fastify-xstripe

Stripe webhook handling for Fastify v5. Registers a POST webhook route with automatic signature verification, dispatches to 23 built-in subscription/invoice/payment/checkout/charge event handlers (all overridable), and decorates fastify.xStripe with the full Stripe SDK client.

Breaking change (pre-1.0 standardization): the Stripe SDK client decorator was renamed from fastify.stripe to fastify.xStripe. Update every fastify.stripe reference in your application when upgrading. Option-validation error messages were also standardized — see the Error Reference.

Installation

npm install @xenterprises/fastify-xstripe stripe

Quick Start

import Fastify from "fastify";
import xStripe from "@xenterprises/fastify-xstripe";

const fastify = Fastify({ logger: true });

await fastify.register(xStripe, {
  apiKey: process.env.STRIPE_API_KEY,          // consumer owns env access
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

// Full Stripe SDK available anywhere
const customer = await fastify.xStripe.customers.create({ email: "user@example.com" });

await fastify.listen({ port: 3000 });

The plugin never reads process.env itself — your application reads the environment and passes every value in via options.

Options

All options are validated at registration; invalid or missing options throw before the server starts.

Decorated Properties

Pages

• Webhook Route — The POST /stripe/webhook handler: signature verification, dispatch, custom handler authoring, and testing.
• Helpers — Utility functions for formatting amounts, resolving subscription state, extracting invoice data, and more.

Custom Handlers

Override any default handler with your business logic. Each handler receives (event, fastify, stripe):

await fastify.register(xStripe, {
  apiKey: process.env.STRIPE_API_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  handlers: {
    "customer.subscription.created": async (event, fastify, stripe) => {
      const sub = event.data.object;
      await db.users.update({
        where: { stripeCustomerId: sub.customer },
        data: { subscriptionId: sub.id, status: sub.status },
      });
    },
    "invoice.payment_failed": async (event, fastify, stripe) => {
      const invoice = event.data.object;
      const customer = await stripe.customers.retrieve(invoice.customer);
      await sendEmail(customer.email, "Payment Failed", "Please update your card.");
    },
  },
});

Default Event Handlers

All 23 built-in handlers log structured data via fastify.log. Override any via the handlers option. Events with no matching handler are acknowledged with processed: false.

Subscription Events

Invoice Events

Payment Events

Customer Events

Payment Method Events

Checkout Events

Charge Events

Helper Utilities

Import from @xenterprises/fastify-xstripe/helpers or via named export:

import { helpers } from "@xenterprises/fastify-xstripe";

Error Reference

All errors are plain Error objects whose messages name the plugin (xstripe), the option, and a usage example.

Startup Errors (thrown at registration)

Webhook Runtime Errors (HTTP 400)

Handler exceptions are logged and acknowledged with HTTP 200 ({ received: true, processed: false, error }) so Stripe does not immediately retry.

Environment Variables

The plugin never reads process.env itself. These variables are the consumer-side convention: your application reads them and passes the values into app.register(xStripe, { ... }).

How It Works

On registration, the plugin validates all options, initializes the Stripe SDK with the provided apiKey and apiVersion, and decorates fastify.xStripe. A POST route is registered at webhookPath inside an encapsulated context with a raw-body content parser (required for signature verification, so no extra Fastify configuration is needed). The route verifies the Stripe signature using stripe.webhooks.constructEvent() before any processing, then dispatches the event to the resolved handler — user handlers are merged over defaults via object spread ({ ...defaultHandlers, ...handlers }). If a handler throws, the error is logged but the route still returns HTTP 200 to prevent Stripe from retrying the event. The fastify.xStripe decorator gives full programmatic access to the Stripe SDK for any API call outside the webhook flow.

Testing Webhooks Locally

# Install Stripe CLI and forward webhooks to your local server
stripe listen --forward-to localhost:3000/stripe/webhook

# Trigger test events
stripe trigger customer.subscription.created
stripe trigger invoice.payment_failed
stripe trigger checkout.session.completed

AI Context

package: "@xenterprises/fastify-xstripe"
type: fastify-plugin
use-when: Stripe webhook handling with signature verification and full Stripe SDK access
decorator: fastify.xStripe (full Stripe SDK client — renamed from fastify.stripe in the pre-1.0 standardization)
webhook-route: POST /stripe/webhook (configurable via webhookPath)
default-handlers: 23 built-in handlers for subscription/invoice/payment/customer/checkout/charge events — all overridable
env: STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET — consumer reads env and passes values via options; the plugin never reads process.env
helper-exports: formatAmount, getPlanName, isActiveSubscription, isInTrial, getDaysUntilTrialEnd, calculateMRR, and more