Backend

You need a backend if your app needs to:

• Store data long-term (user preferences, linked accounts, custom records)
• Call APIs that require server-side secrets (API keys that can’t be in the browser)
• Run logic when the user isn’t in the Dashboard (webhooks, scheduled jobs)
• Call third-party services securely (email providers, CRMs, spreadsheet APIs)
• Perform actions that take longer than the UI can wait for

You don’t need a backend if:

• Your app only reads and displays Stripe data (use the SDK client directly in the UI)
• You only need to store a small amount of sensitive data — use the Secret Store API instead

Canonical documentation

Before writing backend code, read these pages using WebFetch:

Backend architecture decisions

Authentication type determines the backend pattern

Your app’s stripe_api_access_type controls how the backend authenticates. See authentication.md for the full breakdown of auth types and when to use each one.

CORS configuration

CORS (Access-Control-Allow-Origin: *) is needed ONLY on endpoints called by the UI extension. The UI runs in a sandboxed iframe with a null origin — specific origin allowlisting will not work.

Webhook endpoints do NOT need CORS — they receive requests from Stripe’s servers, not from the browser.

fetchStripeSignature verification

fetchStripeSignature is how the UI extension authenticates requests to your backend. The signed payload and verification method are documented at https://docs.stripe.com/stripe-apps/build-backend (opens in a new tab).

Key facts:

• The signing secret (starts with absec_...) is generated on first stripe apps upload
• The default signed payload contains user_id and account_id (field order matters)
• Extra data can be included by passing it to fetchStripeSignature(payload)
• Verification uses stripe.webhooks.signature.verifyHeader()

Webhook configuration

Webhook setup depends on your app’s distribution and auth type:

The event_read permission MUST be declared in your manifest, plus read permissions for each event type you want to receive.

Read https://docs.stripe.com/stripe-apps/events (opens in a new tab) for the full setup guide.

For firewall allowlisting of inbound webhook traffic, see https://docs.stripe.com/ips (opens in a new tab) for Stripe’s IP addresses.

Secret Store API

Plain-language: “Stripe has a built-in secure place to store passwords, tokens, and API keys for your app — you don’t need to build your own database for secrets.”

Two scopes

Limits and restrictions

• Maximum 10 secrets per scope (account and user separately)
• Always list and delete before adding more if approaching the limit
• Do not store PCI-sensitive data (card numbers, CVVs, bank account numbers)

Declaring the permission

In stripe-app.yaml:

Implementation

For the correct code patterns to read, write, and delete secrets, read: https://docs.stripe.com/stripe-apps/store-secrets (opens in a new tab)

Local development with a backend

Run your backend locally alongside stripe apps start:

For webhook forwarding during local development, see references/webhooks.md.