Skip to content

: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.

11.2 KB
Raw Blame

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:

  1. 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 PostHog Integration model (sensitive_config.access_token) and is used server-side for data imports and for writing secrets to Stripe.

  2. 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 — StripeIntegration class: writes and clears secrets in Stripe
  • posthog/api/integration.py — triggers write_posthog_secrets() after Stripe OAuth callback
  • posthog/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 Store
  • src/posthog/client.ts — authenticated HTTP client for PostHog APIs
  • src/components/PostHogConnect.tsx — connection status UI + dev-mode token entry
  • src/views/ — Stripe Dashboard view entry points (Home, FullPage, Settings, Onboarding)
  • src/fullPage/ — tabs, data fetching, and helper components for the full-page view
  • src/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, CSP
  • stripe-app.dev.json — extends the production manifest, overrides URLs to localhost: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:

  1. Look for the token output in the dev server logs (or phrocs stripe-app pane).
  2. 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.
  3. 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.

  1. 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_.../authorize
    

    The STRIPE_APP_OVERRIDE_AUTHORIZE_URL must be a channel link URL (not the standard marketplace URL) because channel links allow non-published app versions to be installed.

  2. Start the OAuth flow from PostHog (localhost:8010). PostHog redirects to Stripe's authorize page.

  3. Stripe redirects back to the redirect_uri — which is derived from SITE_URL and will be https://localhost:8010/integrations/stripe/callback (or https://us.posthog.com/... if that's your SITE_URL).

    Since Stripe requires HTTPS redirect URIs, and localhost doesn't have a valid HTTPS certificate, you have two options:

    a. Temporarily set SITE_URL to 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 to localhost: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_URL to that URL.

  4. 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.

  1. Bump the version in both stripe-app.json and package.json. Stripe rejects an upload whose version is already published. The upload regenerates package-lock.json from package.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.

  2. Upload.

    cd services/stripe-app
    pnpm run upload
    

    This creates a package-lock.json (required by Stripe) and uploads the app. Stripe then processes the files, which is not instant.

  3. 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)