:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
PostHog Stripe App
A Stripe App that surfaces PostHog product analytics data directly inside the Stripe Dashboard.
Architecture
Double OAuth flow
Connecting PostHog to Stripe requires two OAuth exchanges in sequence:
Stripe OAuth (Stripe → PostHog): the user clicks "Connect" in PostHog, which redirects them to
marketplace.stripe.com/oauth/v2/authorize. Stripe asks the user to grant PostHog access to their Stripe account. On success Stripe redirects back to PostHog with an authorization code that PostHog exchanges for a Stripe access token. This token is stored in the PostHogIntegrationmodel (sensitive_config.access_token) and is used server-side for data imports and for writing secrets to Stripe.PostHog OAuth (PostHog → Stripe Secret Store): immediately after the Stripe token exchange, the PostHog backend creates a PostHog OAuth access + refresh token pair (scoped to the team) and writes them — along with the region (
us/eu) — into Stripe's Secret Store via the Stripe API. The Stripe App reads these secrets at runtime to call PostHog APIs.
The three secrets stored in Stripe are:
| Secret name | Value |
|---|---|
posthog_region |
us or eu |
posthog_access_token |
PostHog OAuth token |
posthog_refresh_token |
PostHog OAuth refresh |
PostHog backend
Key files:
posthog/models/integration/stripe.py—StripeIntegrationclass: writes and clears secrets in Stripeposthog/api/integration.py— triggerswrite_posthog_secrets()after Stripe OAuth callbackposthog/settings/integrations.py— env vars (STRIPE_APP_CLIENT_ID,STRIPE_APP_SECRET_KEY,STRIPE_POSTHOG_OAUTH_CLIENT_ID,STRIPE_APP_OVERRIDE_AUTHORIZE_URL)
Stripe App (this directory)
src/posthog/auth.ts— reads/writes/clears credentials in Stripe's Secret Storesrc/posthog/client.ts— authenticated HTTP client for PostHog APIssrc/components/PostHogConnect.tsx— connection status UI + dev-mode token entrysrc/views/— Stripe Dashboard view entry points (Home, FullPage, Settings, Onboarding)src/fullPage/— tabs, data fetching, and helper components for the full-page viewsrc/constants.ts— typed access to manifest constants (PostHog URLs)
Full Page view
The full-page view (stripe.dashboard.fullpage viewport, entry in src/views/FullPage.tsx)
renders a five-tab PostHog dashboard inside Stripe: Overview, Events, Experiments,
Feature flags, Sessions. Overview shows web-analytics-style stat cards (visitors / views /
sessions / bounce rate) wired to the PostHog WebOverviewQuery, plus trends/funnel/lists.
Experiments and Feature flags are wired to real PostHog API endpoints; Events and Sessions
are mock fixtures that can be swapped for real data later.
This viewport is part of Stripe's alpha-stage Full Page Apps feature and is gated per
app_id + account_id. If the dashboard redirects to home when visiting
/app/com.posthog.stripe, ask Stripe to enable the feature flag for your merchant account.
Real data paths require two things in Stripe's Secret Store:
| Secret name | Value |
|---|---|
posthog_project_id |
Numeric PostHog project ID used for API calls |
…in addition to the OAuth credentials above. The PostHog backend writes posthog_project_id
alongside the tokens. When missing, the Experiments / Feature flags tabs render a "not linked"
banner and the Overview falls back to mock summaries.
In dev mode, open the Stripe Dashboard and navigate to /app/com.posthog.stripe (append a
tab id like /app/com.posthog.stripe/overview to deep-link directly into a tab).
Manifest files
stripe-app.json— production manifest: PostHog URLs, permissions, CSPstripe-app.dev.json— extends the production manifest, overrides URLs tolocalhost:8010
Development
Prerequisites
- Stripe CLI installed and authenticated (
stripe login) - PostHog running locally on
localhost:8010
Running the app locally
You can configure phrocs to include the stripe app in your configuration when running hogli dev:setup. If you don't wanna change your phrocs setup, however, you can run it manually
# Via hogli (recommended — also starts via phrocs)
hogli start:stripe:app
# Or directly
pnpm --filter=@posthog/stripe dev
This runs stripe apps start --manifest stripe-app.dev.json,
which serves the app UI inside the Stripe Dashboard in test mode.
Connecting to PostHog locally
There are two approaches depending on whether you need to test the OAuth flow itself.
Quick approach: paste tokens from the startup logs
The dev server automatically generates PostHog OAuth tokens on startup
(via manage.py generate_stripe_app_tokens).
You'll see the tokens printed in the logs when the server starts — no manual command needed.
The tokens are reused across restarts as long as they haven't expired (24 hours).
If you need fresh ones, run the command manually with --force:
python manage.py generate_stripe_app_tokens --team-id=1 --force
On first run, if STRIPE_POSTHOG_OAUTH_CLIENT_ID is not set,
the command will automatically create an OAuthApplication
and write its client_id to your .env.
To connect the app:
- Look for the token output in the dev server logs (or phrocs
stripe-apppane). - In the Stripe Dashboard, navigate to the PostHog app
(it runs in test mode when started via
stripe apps start). The "Not connected" screen shows a Dev mode section at the bottom with fields for region, access token, and refresh token. - Paste the values and click Save tokens.
The app stores them in Stripe's Secret Store just like the production flow would, and the connection is established.
By default the startup script uses team ID 1.
Pass a different ID as an argument: bin/start-stripe-app 42.
Full approach: test the complete OAuth flow
If you need to test the actual double OAuth exchange end-to-end,
you need to work around the fact that Stripe's OAuth redirect cannot target localhost.
The trick is to temporarily route through a production URL and then redirect back locally.
Set up environment variables in your
.env:STRIPE_APP_CLIENT_ID=ca_... # from Stripe Apps dashboard STRIPE_APP_SECRET_KEY=sk_test_... # from Stripe API keys STRIPE_POSTHOG_OAUTH_CLIENT_ID=... # auto-created by the management command, or create manually STRIPE_APP_OVERRIDE_AUTHORIZE_URL=https://marketplace.stripe.com/oauth/v2/chnlink_.../authorizeThe
STRIPE_APP_OVERRIDE_AUTHORIZE_URLmust be a channel link URL (not the standard marketplace URL) because channel links allow non-published app versions to be installed.Start the OAuth flow from PostHog (localhost:8010). PostHog redirects to Stripe's authorize page.
Stripe redirects back to the
redirect_uri— which is derived fromSITE_URLand will behttps://localhost:8010/integrations/stripe/callback(orhttps://us.posthog.com/...if that's yourSITE_URL).Since Stripe requires HTTPS redirect URIs, and
localhostdoesn't have a valid HTTPS certificate, you have two options:a. Temporarily set
SITE_URLto a production URL (e.g.https://us.posthog.com), start the OAuth flow, then once Stripe redirects to that production URL, copy the callback URL from the browser, change the host tolocalhost:8010, and paste it into your browser to complete the flow locally.b. Use a tunnel (e.g. ngrok, Cloudflare Tunnel) to expose your local PostHog on a public HTTPS URL and set
SITE_URLto that URL.PostHog completes the exchange: exchanges the authorization code for a Stripe access token, creates PostHog OAuth tokens, and writes all three secrets to Stripe's Secret Store.
The full approach is more involved but tests the entire production flow. For day-to-day development, the quick approach is recommended.
Releasing
Merging a manifest change does not ship it. A release is three steps, and an uploaded version is not a published one: every install keeps running the last published version until someone publishes the new one in the Stripe dashboard.
Bump the version in both
stripe-app.jsonandpackage.json. Stripe rejects an upload whose version is already published. The upload regeneratespackage-lock.jsonfrompackage.json, so bumping only the manifest sends Stripe a lockfile that disagrees with it. Use semver: patch for fixes, minor for new fields/features, major for breaking changes.Upload.
cd services/stripe-app pnpm run uploadThis creates a
package-lock.json(required by Stripe) and uploads the app. Stripe then processes the files, which is not instant.Publish the version in the Stripe dashboard. Until then, installs stay on the previously published version, whatever this repo says.
Nothing in CI checks that a merged manifest change was ever uploaded or published, and a failed upload leaves no trace here. Version 1.4.0 sat unpublished for 18 days for exactly that reason. Confirm the version is live in the dashboard before treating a manifest change as shipped.
Permissions Stripe refuses
Stripe rejects a manifest that requests certain permissions, failing the upload with
requesting <name> permission is disallowed. webhook_write is one of them, which is
why OAuth-connected warehouse sources cannot create webhooks and point the user at
manual setup instead. A restricted API key can still hold those permissions, so the
source keeps rak_webhook_write in its PERMISSIONS list while the manifest omits it.
MANIFEST_DISALLOWED in test_stripe_source.py tracks the refused set, and a test
fails if the manifest reintroduces one. When Stripe refuses a new permission, add it
there rather than dropping it from PERMISSIONS.
What the two permission lists control
permissions is what the app may do inside the user's Stripe account.
provisioning.oauth_scopes is the scope set PostHog grants Stripe's own OAuth token
for provisioning calls. The PostHog personal API key handed to a provisioned Stripe
Projects user currently copies that token's scopes, so widening this list widens both.
That key widens only on a fresh account request, because a refresh carries previous
scopes forward.
Environment variables
| Variable | Description |
|---|---|
STRIPE_APP_CLIENT_ID |
Stripe App OAuth client ID (from Stripe Apps dashboard) |
STRIPE_APP_SECRET_KEY |
Stripe API secret key for token exchange |
STRIPE_POSTHOG_OAUTH_CLIENT_ID |
Client ID of the PostHog OAuthApplication used by the Stripe App |
STRIPE_APP_OVERRIDE_AUTHORIZE_URL |
Channel link authorize URL (required for non-published app installations) |