PostHog
Open-source product analytics platform. Send events, identify users, and update group properties to PostHog via the Batch API. Supports PostHog Cloud (US and EU regions) and self-hosted instances.
Prerequisites
- A PostHog account (Cloud or self-hosted)
- Your PostHog project API key
Authentication
PostHog uses Project API Key authentication.
- In PostHog, go to Settings > Project Settings
- Copy the Project API Key (starts with
phc_) - Enter the value in Zeotap
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Host | Select | Yes | PostHog instance URL: US Cloud, EU Cloud, or Self-Hosted. Default: US Cloud (https://us.i.posthog.com) |
For self-hosted installations, select Self-Hosted and enter your PostHog instance URL.
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Event Type | Select | Yes | Type of data to send: Capture Events, Identify Users, or Group Identify |
| Group Type | Text | Conditional | The group type key (e.g. company, project). Required when Event Type is Group Identify |
Supported Operations
Sync Modes: Upsert, Insert
| Mode | Supported |
|---|---|
| Upsert | Yes |
| Insert | Yes |
| Update | — |
| Mirror | — |
Audience Sync Modes: Add, Upsert
| Mode | Supported |
|---|---|
| Add | Yes |
| Upsert | Yes |
| Remove | — |
| Mirror | — |
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Event Type | Required Fields |
|---|---|
| Capture Events | distinct_id, event |
| Identify Users | distinct_id |
| Group Identify | group_key |
Default Destination Fields
Capture Events: distinct_id, event, timestamp, properties
Identify Users: distinct_id, timestamp, set (person properties via $set), set_once (person properties via $set_once)
Group Identify: group_key, timestamp, group_properties
How It Works
Zeotap sends data to PostHog using the Batch API (/batch endpoint). Events are chunked into batches of up to 1,000 per request.
Capture Events
Each row is sent as a PostHog capture event. The event field sets the event name and all other mapped fields are included as event properties.
Identify Users
Each row is sent as a PostHog $identify event. Mapped fields are included in the $set property to update person profiles. Use the set_once field for properties that should only be set if not already present.
Group Identify
Each row is sent as a PostHog $groupidentify event. The group_key identifies the specific group instance within the configured group type. All other mapped fields are included as group properties.
Rate Limits
PostHog does not enforce rate limits on the capture/batch endpoints. The payload size limit is 20 MB per request. Zeotap batches events into groups of 1,000 to stay well within this limit.
Best Practices
- Use Capture Events for tracking user actions and behavioral data
- Use Identify Users to keep person properties (name, email, plan, etc.) in sync
- Use Group Identify to maintain company or project-level properties for group analytics
- The
distinct_idshould match the identifier used in your PostHog client-side instrumentation - For self-hosted instances, ensure the PostHog instance URL is accessible from Zeotap
Troubleshooting
Events not appearing in PostHog
PostHog processes events asynchronously. Events may take a few minutes to appear in the dashboard. Check the Activity page in PostHog to verify events are being received.
Invalid API key
Ensure you are using the Project API Key (starts with phc_), not a personal API key. Navigate to Settings > Project Settings in PostHog to find the correct key.
Person properties not updating
When using Identify mode, verify that the distinct_id matches existing PostHog person records. Properties sent via $set overwrite existing values, while $set_once only sets values that are not already present.
Group properties not appearing
Group analytics requires the group analytics add-on. Verify that the group type configured in Zeotap matches a group type defined in your PostHog project under Settings > Project Settings > Group Analytics.
Self-hosted connection failures
Ensure your PostHog instance URL is correct and accessible. The URL should include the protocol (e.g., https://posthog.yourcompany.com). Check that no firewall rules are blocking outbound connections from Zeotap.
Large batch failures
PostHog limits request payloads to 20 MB. If individual rows contain large JSON properties, reduce the number of mapped fields or filter out unnecessarily large values in your model.