/Integrations
v1.2Stripe
Validate Stripe credentials, webhook routing, and shadow Checkout verification.
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
- 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
Test mode first
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 your project in PreFlight and go to Integrations → Stripe.
- Paste your secret key, webhook URL, and signing secret. Use test-mode keys first.
- Optionally configure shadow Checkout fields (trace table, column, verification window).
- Click Run Pre-Flight Check and confirm all four money-path probes pass.