Connecting PostHog
Connect PostHog with a read-only personal API key, what Oskar reads, and how product usage is matched to your Stripe customers.
PostHog tells Oskar how each customer actually uses your product. That lets Oskar spot a team going quiet, a customer outgrowing their plan, or a new customer who hasn't got going yet. Oskar connects with a personal API key that only needs read access.
What you need#
- Your region: US cloud or EU cloud.
- Your project id: the number in your PostHog project's settings, or in the address bar (
/project/12345). - A personal API key: create one in PostHog under your account's personal API keys. Give it only the read-only query scope, and limit it to the project you're connecting. Oskar needs nothing more.
Connect your project#
- In setup's first step, or later on Integrations, open Connect your PostHog project.
- Choose your region, then enter your project id and personal API key.
- Choose Connect PostHog.
Your key is encrypted when stored, and you can see when Oskar last synced on Integrations.
What Oskar reads#
Every night, Oskar runs one query against your project for the last 28 days. For each person with an email address, it gets how many times they triggered each event on each day. If you match customers by PostHog company group, the query also returns each person's group key.
It doesn't read event properties, session recordings, feature flags, surveys or dashboards, and it never writes to PostHog. Read-only by design has the details.
People without an email address in PostHog can't be matched to a customer, so they aren't included. If your product doesn't set an email on each person, Oskar won't see their usage.
Matching usage to customers#
Stripe knows who pays, and PostHog knows who uses the product. Oskar has to know which people in PostHog belong to which Stripe customer. You confirm the rule during setup, and you can change it later in Settings. There are two options.
By company email domain#
People who use your product with an @acme.com address count towards the Stripe customer whose billing email is @acme.com.
This works well when customers are companies whose staff sign in with work addresses. Shared mail providers (Gmail, Googlemail, Outlook, Hotmail, Yahoo, iCloud and Proton) don't identify a company, so customers billed at those addresses aren't matched this way.
By PostHog company group#
If you use PostHog's group analytics and set each company group's key to the Stripe customer id (cus_…), Oskar matches usage by that key. This is the most precise option. It's only offered when Oskar finds company groups in your project.
Checking the match#
Before you confirm, setup shows how many paying customers have product usage matched to them, with examples of matched and unmatched customers and why. Usage that doesn't match a paying customer is dropped, not stored.
What Oskar works out from usage#
For each customer, Oskar keeps daily totals of product events, events by name, and how many people were active. From those it can tell:
- whether usage is up or down compared with the two weeks before
- how long it's been since anyone used the product, compared with how often healthy customers use it
- whether a customer has stopped using one of your key features
- whether a new customer has reached the action that shows they're set up
- whether as many people use the product as there are paid seats
During setup, Oskar suggests which of your events show real value and which one shows a new customer is set up. You confirm or correct these. See Getting started.
Disconnecting#
Delete the personal API key in PostHog. Oskar's nightly query then fails and it receives nothing more. To delete the data it already holds, email hello@infinitestack.co.