PostHog Destination Config Reference

PostHog is a product analytics destination. RudderStack sends events to PostHog from its servers, or — for web sources — through PostHog’s own SDK in device mode.

In a PostHog destination spec:

• type: posthog
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: posthog-prod
spec:
  id: posthog-prod
  display_name: PostHog Production
  type: posthog
  definition_version: 1
  enabled: true
  config:
    api_key: "{{ .POSTHOG_API_KEY }}"
    endpoint: https://eu.posthog.com
    use_v2_group: true

    autocapture:
      web: true
    capture_page_view:
      web: false
    disable_session_recording:
      web: false
    enable_local_storage_persistence:
      web: true
    person_profiles:
      web: identified_only
    xhr_headers:
      - key: X-Environment
        value: production
    property_blacklist:
      - property: email

    connection_mode:
      web: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics

The above example loads PostHog’s SDK on web sources in device mode, where the web settings apply, and sends server-side events in cloud mode, where use_v2_group applies — see Web device mode.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Connection

Web device mode

These keys configure PostHog’s SDK in the browser, so they apply only to web sources connected in device mode. Most are objects keyed by web; xhr_headers and property_blacklist are plain lists that apply to web all the same.

person_profiles:
  web: identified_only

xhr_headers:
  - key: X-Environment
    value: production

property_blacklist:
  - property: email
  - property: phone

Event filtering

Client-side event filtering is applied by the RudderStack SDK, so it affects only web sources connected in device mode. Events sent in cloud mode aren’t filtered by it.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: device
  cloud: cloud

Source types

PostHog accepts events from these source types in the mentioned connection modes:

Only web offers device mode, which loads PostHog’s SDK in the browser. In cloud mode PostHog accepts alias, group, identify, page, screen, and track; in device mode, web sources send group, identify, page, and track. See PostHog device mode.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers PostHog to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'posthog-prod' config has no 'connection_mode' entry for source type 'web'

PostHog needs no additional config keys to connect a source of any type, in any mode.

Secrets

api_key is the only secret key. Write it as a {{ .VAR }} reference and supply the value at apply time:

config:
  api_key: "{{ .POSTHOG_API_KEY }}"

export RUDDER_POSTHOG_API_KEY="phc_..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.
• In device mode the team API key is embedded in the page’s JavaScript, so masking it protects your YAML, not the value itself.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

See more

• PostHog Destination for the team API key and the device mode settings
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope