Integration
Stripe
Confirms that payments can create events your app can trust.
Stripe launch risk is rarely "can the API key authenticate." Real failures come from webhook routing, signature mismatch, or the downstream side effect never being written after Checkout completes. PreFlight validates the whole money path—not just the credential—before you open checkout to customers.
Requirements
<IntegrationRequirements
items={[
"Restricted secret key or test secret key scoped to the environment you are validating",
"Webhook endpoint URL—the public route your app actually serves",
"Webhook signing secret (whsec_...) from Stripe → Webhooks",
"Optional shadow-check fields for end-to-end Checkout verification",
]}
/>
Validate in Stripe test mode before pointing PreFlight at live keys. The shadow flow uses test-mode Checkout so no real card is ever charged.
What PreFlight checks
| Probe | What it proves |
| --- | --- |
| Key reachability | The secret key authenticates against Stripe and the account is reachable. |
| Webhook reachability | The endpoint URL is public and ready for Stripe event delivery. |
| Signature handshake | The endpoint accepts a correctly signed test event and rejects bad signatures. |
| Webhook registry | The signing secret stored in PreFlight matches the endpoint registered in Stripe. |
| Shadow Checkout | A test-mode Checkout session can be created and later validated as paid. |
| Side-effect verification | The expected row (subscription, entitlement, credit) is written after payment. |
Failure guidance
| Symptom | Fix |
| --- | --- |
| Invalid API key | Create or rotate a valid secret key in Developers → API keys, scoped to the right environment. |
| Webhook signature mismatch | Confirm the route and signing secret match the endpoint deployed in your app. The secret in your env must equal the one shown in Stripe → Webhooks. |
| Endpoint blocked (401/403) | Ensure the route accepts unauthenticated `POST` from Stripe and is not behind auth middleware. |
| Side effect missing | Confirm the trace column, table name, and verification window match your data model. |
| Config drift | Reconcile webhook URL and signing secret between Stripe dashboard and PreFlight. |
Dashboard setup
Open Connections, choose your app, and click Connect Stripe test account.
Approve the Stripe Apps authorization screen. PreFlight stores the short-lived access token and refresh token encrypted, then refreshes the connection before checks and reconciliation runs.
Add the webhook URL and signing secret only when you want signed-delivery and end-to-end payment proof. OAuth cannot infer a secret that Stripe intentionally reveals only at endpoint creation.
Optionally configure shadow Checkout fields (trace table, column, verification window).
Click Run Pre-Flight Check and confirm all four money-path probes pass.
If your Stripe account cannot use the app authorization flow, open the manual method or import `.env.local`. Environment files are parsed in the browser; PreFlight only receives the variables you explicitly confirm.
<RelatedLinks
links={[
{ href: "/docs/guides/verify-stripe-checkout-without-a-real-credit-card", title: "Verify Stripe Checkout without a card", description: "Walk through the full shadow Checkout workflow." },
{ href: "/docs/guides/revenue-watch", title: "Payment Sync", description: "Continuously reconcile paid sessions against your database." },
{ href: "/docs/integrations/supabase", title: "Supabase", description: "Validate the database side effect after payment." },
{ href: "/docs/integrations/environment", title: "Environment", description: "Catch secret leaks before they reach production bundles." },
]}
/>
