Stripe

Stripe tells your app that money moved by calling a webhook, and every feature that takes money needs those events. This module receives them once: it verifies each event, skips duplicates and passes it to whoever listens. It also links each user to a Stripe customer. You rarely install it on its own: Payments and Subscriptions install it for you.

The package is @frigear-nu/stripe. It stores no products or prices, only each user's Stripe customer id.

What you get

• Server routes (on by default): one webhook endpoint at /api/stripe/webhook.
• Composables and helpers (on by default): a shared Stripe client, a Stripe customer for any user, and two ways to listen to events.

Quick setup

pnpm add @frigear-nu/stripe @nuxthub/core

export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/stripe'], // installs Users for you
  hub: { db: { dialect: 'sqlite', driver: 'libsql' }, kv: true },
})

pnpm db:generate

Options

Options go under the stripe key.

settings.webhookPath gets a leading / when it has none. @frigear-nu/stripe exports the default as DEFAULT_WEBHOOK_PATH, and the pinned API version as STRIPE_API_VERSION (currently 2026-09-30.endive).

Runtime config

Keys are secrets, so set them through runtime config, never process.env.

Server

These helpers are auto-imported in Nitro.

useStripe() throws 501 not_configured when the secret key is missing.

ensureStripeCustomer first reads the stored id, then searches Stripe by email, then creates a customer and stores it. Concurrent calls end up with one id. An unknown user throws 404.

@frigear-nu/stripe/utils exports registerStripeEventHandler, onStripeEvent and defineStripeEventHandler, and runs outside Nuxt as well. Module authors who send people to Stripe validate return URLs with resolveSameOriginUrl(event, url, { fallback, name }) from @frigear-nu/module-kit/server.

Listen to events

Register a handler at build time from a module, or at runtime from your app.

type StripeEventHandlerContext = {
  stripe: Stripe          // the useStripe() instance
  userId: number | null   // local user owning the event's customer, null if unknown
  event: H3Event          // the Nitro event of the webhook request
}

type StripeEventHandler<T extends StripeEventType = StripeEventType> = (
  event: StripeEventOf<T>,
  ctx: StripeEventHandlerContext,
) => void | Promise<void>

// Build time, from a module's setup()
registerStripeEventHandler(nuxt: Nuxt, options: {
  events: string[] | '*'  // Stripe event types, or '*' for every event
  handler: string         // absolute path to a file whose default export is a defineStripeEventHandler(...) result
  order?: number          // lower runs first, default 100
}): void

// Runtime, from a Nitro plugin
onStripeEvent<T extends StripeEventType>(
  type: T | T[] | '*',
  handler: StripeEventHandler<T>,
): void

In a module

A module registers a handler file from setup():

import { createResolver, defineNuxtModule } from '@nuxt/kit'
import { registerStripeEventHandler } from '@frigear-nu/stripe/utils'

export default defineNuxtModule({
  meta: { name: '@frigear-nu/example' },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)
    registerStripeEventHandler(nuxt, {
      events: ['customer.subscription.updated', 'checkout.session.completed'],
      handler: resolver.resolve('./runtime/server/stripe/example-events'),
      order: 10,
    })
  },
})

import { defineStripeEventHandler } from '@frigear-nu/stripe/utils'

export default defineStripeEventHandler<'customer.subscription.updated' | 'checkout.session.completed'>(
  async (event, { stripe, userId }) => {
    // `event` is narrowed to the generic's event types. Must be idempotent.
    if (!userId) return
  },
)

Handler files are bundled into #stripe/handlers after every module's setup(), so the registration order does not matter.

In your app

export default defineNitroPlugin(() => {
  onStripeEvent('invoice.payment_failed', async (event, ctx) => {
    // notify the user, flag the account, ...
  })
})

Runtime handlers have order 100. They run after build-time handlers of the same order.

Delivery and retries

• Matching handlers run one after another, sorted by order. Handlers of equal order keep their registration order.
• An error in one handler is logged, and the others still run.
• If any handler throws, the webhook answers 500 and Stripe retries the whole event. So every handler must be idempotent.
• The event id is stored in KV, under stripe:event:<event id> for 7 days, only after all handlers succeed. A duplicate delivery is then acknowledged without running them again.

Hooks

Your app can also answer this Nitro hook from a server plugin (server/plugins/*.ts).

Errors in stripe:event are logged and never fail the webhook.

Routes

Routes the module registers, and who may call them.

Database

Tables the module adds. Generate and commit a migration after installing.

The module adds one nullable column to users, through a database extension: stripeCustomerId (stripe_customer_id). Do not add it to your own server/db/extend.sqlite.ts.

Next steps

• Stripe setup – connect your Stripe account and pick the webhook events.
• Sell event tickets – follow one payment from checkout to a webhook event.