PostHog

Configuration

To configure PostHog as a destination for your tracked events, add the following to your pg_track_events.config.yaml file:

destinations:
  posthog:
    apiKey: "YOUR_API_KEY_HERE" # or use an environment variable (see below)

Configuration Options

filter: Event name glob filter (optional) Learn about filtering events
apiKey: Your PostHog project API key (required). Can be hardcoded directly in the YAML or reference an environment variable.
endpoint: (optional) Custom API endpoint URL for PostHog. Defaults to PostHog Cloud US.

Getting Your PostHog API Key

To find your project API key:

Log in to your PostHog account
Go to Project Settings > Project API Keys
Copy your project API key (it starts with phc_)

Distinct IDs

The system automatically extracts a distinct ID from your event properties for user identification in the following order:

distinct_id property
Common user ID fields (user_id, userid, _user_id)
For tables named users, user, or _users, it will look for an id field

If no ID is found, the distinct ID will be null.

PostHog will reject events with missing distinct IDs

If no distinct ID is found or is null/empty, PostHog will reject the events and they will accumulate in the outbox table in your PostgreSQL database. Make sure to always include a valid distinct ID in your event properties to ensure proper event processing when sending to PostHog.

Note

After making configuration changes, restart the pg_track_events agent for them to take effect.