Configuration

type PayloadPosthogConfig = {
  apiKey: string // required unless disabled: true
  host?: string // default: https://us.i.posthog.com
  personalApiKey?: string // enables local flag evaluation + the admin flags widget's management-API calls
  disabled?: boolean // keep the plugin registered but turn off all runtime behavior

  capture?: boolean | CaptureConfig // default: true
  collections?: CollectionSlug[] | Partial<Record<CollectionSlug, CollectionCaptureConfig>>
  identify?: boolean | IdentifyConfig // default: true
  featureFlags?: boolean | FeatureFlagsConfig // default: true
  errorTracking?: boolean | ErrorTrackingConfig // default: true
  client?: boolean | ClientConfig // default: true
  proxy?: boolean | ProxyConfig // default: false (opt-in)
  webhooks?: WebhooksConfig // no default — provide a handler to enable
  groups?: GroupsConfig // no default — provide a mapper to enable
  admin?: { dashboardWidget?: boolean } // default: true

  posthogOptions?: Partial<PostHogNodeOptions> // passthrough to `new PostHog()`
}

Every boolean | XConfig option accepts true/false as shorthand for "defaults on/off", or an object for detailed control — that pattern repeats across every feature. Full type definitions ship with the package; import them standalone from payload-posthog/types or rely on your editor's autocomplete on the plugin options object.

distinctId resolution

Every feature that needs a distinctId accepts its own distinctId override and otherwise falls back to defaultResolveDistinctId, exported from the package:

The acting user's email
The acting user's id
SYSTEM_DISTINCT_ID ('system') — for unauthenticated or system-initiated operations (webhooks, seed scripts, cron jobs), so they're still captured under a generic actor instead of silently dropped

Return undefined from your own distinctId override to skip capture for a given event instead of falling back to 'system'.

import { defaultResolveDistinctId, SYSTEM_DISTINCT_ID } from 'payload-posthog'

The PostHog client

The plugin initializes a single posthog-node client the moment it runs, and exports it directly:

import { getPostHogClient } from 'payload-posthog'

const client = getPostHogClient()
// any posthog-node method is available here

This is the main escape hatch for anything the plugin's feature modules don't wrap — group analytics beyond $groups tagging, custom event batching options, local feature-flag polling controls, and so on.

distinctId resolution

The PostHog client

On this page