Configure destinations for PostHog

PostHog is a product analytics platform. It captures product events and maintains person and group profiles that teams use to analyze and segment product usage.

The PostHog connector sends person and group properties, events, and deletion requests from Amperity into a PostHog project. What each row becomes — a person-property update, a group-property update, a captured event, or a person deletion — is set by the Write mode setting on the orchestration that sends to this destination.

Each row is addressed by a single identity. The query results must include a column named identity_value that carries that identity: the PostHog distinct_id in person-properties and events modes, the group key in group-properties mode, or the person to delete in person-deletion mode. What Amperity does with the other columns depends on the write mode — see Write modes.

Person-properties and group-properties modes sync incrementally: Amperity sends only the rows whose attributes changed since the last successful run, and reports unchanged rows as sent from cache. Events and person-deletion modes have no incremental tracking — they process every row in the query results on each run, so scope those queries to the rows you intend to send.

Important

The connector reads each row’s identity from a column named identity_value. If your query produces the identity under another name, alias it — for example SELECT distinct_id AS identity_value. A send whose query results have no identity_value column fails before any data is sent, with a message naming the missing column.

Note

This destination uses the PostHog API — the capture API for property, group, and event writes, and the Persons API for person deletion.

Beta

The PostHog connector is currently in beta. Contact your Amperity representative to learn more.

Important

A successful connection test confirms that PostHog is reachable and that both keys are well-formed. It does not confirm that data is landing. PostHog’s capture endpoint accepts any well-formed Project API Key without verifying that it belongs to your project, so a wrong key — including a phs_ Project Secret API Key — passes the test and then silently drops every record. Use the classic Project API Key (it starts with phc_), and after your first run confirm that records appear on PostHog’s Persons page.

Note

Configure one orchestration per write mode, each sending its own query. To send more than one write mode against the same PostHog project, configure a separate orchestration, with its own query, for each.

Write modes

The Write mode setting selects what each row does, and an orchestration performs a single write mode for the entire run. You choose the write mode, and its mode-specific settings, when you configure the orchestration that sends to this destination.

Write mode	What it sends
person-properties	The default. Writes each row as properties on a PostHog person, addressed by identity_value as the distinct_id. Every column other than identity_value becomes a person property, written with $set (overwrite on every run) or, for columns named in the Set-once properties setting, $set_once (written once, never overwritten). Syncs incrementally.
group-properties	Writes each row as properties on a PostHog group, addressed by identity_value as the group key. Requires the Group type setting. Every column other than identity_value becomes a group property. Syncs incrementally.
events	Captures each row as a PostHog event. Requires the Event name column and Timestamp column settings, which name the columns that supply the event name and event time; every column other than those two and identity_value becomes an event property. Processes every row on each run.
person-deletion	Permanently deletes each row’s person from PostHog, addressed by identity_value. Only identity_value is used; other columns are ignored. Optionally also deletes each person’s events and session recordings — see the Delete events and Delete recordings settings. Processes every row on each run.

In person-properties and group-properties modes, you can SHA-256 hash specific columns before sending with the Hashed properties setting. PostHog stores properties as literal, queryable values, so hash a column only when your own policy requires it — a hashed value can no longer be searched or filtered in PostHog.

Caution

In group-properties mode, PostHog also creates a person record for each group’s key. Syncing a large number of groups adds an equal number of synthetic person records to your PostHog project, alongside the people you actually track, which can inflate person counts and clutter the Persons list. This is a property of how PostHog ingests group updates, not a setting Amperity can change.

Caution

person-deletion mode permanently removes each person from PostHog and cannot be undone. Restrict these orchestrations to the people you intend to delete.

Get details

Review the following details before configuring credentials for PostHog and before configuring Amperity to send person and group properties, events, and deletion requests to a PostHog project.

	Credential settings Required Both credential fields are required. No call can be made without them. Project API Key The PostHog Project API Key, a write-only capture token that authenticates every property, group, and event write this connector sends. Copy it from Project Settings > Project API Key in PostHog. Important Use the classic Project API Key, which starts with phc_ — not a Project Secret API Key, which starts with phs_. Both look valid, but a secret key is accepted by the connection test and then silently drops every record. After your first run, confirm records appear on PostHog’s Persons page. Personal API Key The PostHog Personal API Key, used to verify the connection and, in person-deletion mode, to delete people through PostHog’s Persons API. Create it in PostHog under Account Settings > Personal API Keys. For person-deletion mode, the key must be scoped to allow person deletion (the person:write scope).
	Required configuration setting Identity column The column in the query results that carries each row’s identity: the PostHog distinct_id in person-properties and events modes, the group key in group-properties mode, or the person to delete in person-deletion mode. This is always identity_value — your query must return a column with that exact name.
	Optional destination settings PostHog host Which PostHog deployment this destination sends to: us (the default) or eu for PostHog Cloud, or self-hosted for a customer-hosted PostHog instance. When this is set to self-hosted, the Self-hosted URL setting is required. Self-hosted URL The base URL of your self-hosted PostHog instance — for example https://posthog.example.com. Required when PostHog host is self-hosted, and ignored otherwise. If PostHog host is self-hosted and this is left blank, the run fails. Set-once properties Applies to person-properties mode only. A comma-separated list of column names to write with PostHog’s $set_once semantics — written once and never overwritten — instead of the default $set, which overwrites on every run. Leave it blank to write every non-identity column with $set. A name that is not a column in the query results, or the identity column itself, fails the run before any data is sent. Hashed properties Applies to person-properties and group-properties modes. A comma-separated list of column names to SHA-256 hash (trimmed and lowercased) before sending. Leave it blank to send every column as-is. PostHog stores properties as literal, queryable values, so hash a column only when your own policy requires it — a hashed value can no longer be searched or filtered in PostHog. A name that is not a column in the query results, or the identity column itself, fails the run before any data is sent.
	Orchestration settings These are chosen for each orchestration that sends to this destination, not on the destination itself. Write mode What each orchestration sends to PostHog. A destination performs one write mode per orchestration; to send more than one, configure a separate orchestration, with its own query, for each mode: person-properties (the default) writes each row as properties on a PostHog person, using $set — or $set_once for columns named in Set-once properties. group-properties writes each row as properties on a PostHog group, using the row’s identity as the group key. Requires the Group type setting. events captures each row as a PostHog event, taking the event name and event time from the columns named by Event name column and Timestamp column. Requires both settings. person-deletion permanently deletes each row’s person from PostHog, through the Persons API. Intended for honoring data-subject deletion requests. You choose the write mode when you configure the orchestration that sends to this destination. Group type Applies to group-properties mode only, and is required for it. The PostHog group type this orchestration writes — for example company. PostHog allows up to five group types per project; a value beyond that limit is rejected by PostHog when the run sends. Event name column Applies to events mode only, and is required for it. The name of the column in the query results that supplies each row’s PostHog event name. This column is used as the event name and is not also sent as an event property. If the named column is not in the query results, the run fails before any data is sent. Timestamp column Applies to events mode only, and is required for it. The name of the column in the query results that supplies each row’s event time, so events reflect when they actually happened rather than when they were sent. This column is used as the timestamp and is not also sent as an event property. If a row’s value is empty, PostHog records that event at ingest time instead. If the named column is not in the query results, the run fails before any data is sent. Delete events Applies to person-deletion mode only. When enabled, PostHog also queues each deleted person’s events for deletion. Off by default, which removes the person record without cascading to their events. Delete recordings Applies to person-deletion mode only. When enabled, PostHog also queues each deleted person’s session recordings for deletion. Off by default.

Configure credentials

Configure credentials for PostHog before adding a destination.

An individual with access to PostHog should use SnapPass to securely share “Project API Key” and “Personal API Key” details with the individual who configures Amperity.

To configure credentials for PostHog

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select PostHog. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “posthog” credential type, configure settings, and then click Save. Required Both credential fields are required. Project API Key The PostHog Project API Key, a write-only capture token that authenticates every property, group, and event write this connector sends. Copy it from Project Settings > Project API Key in PostHog. Important Use the classic Project API Key, which starts with phc_ — not a Project Secret API Key, which starts with phs_. Both look valid, but a secret key is accepted by the connection test and then silently drops every record. After your first run, confirm records appear on PostHog’s Persons page. Personal API Key The PostHog Personal API Key, used to verify the connection and, in person-deletion mode, to delete people through PostHog’s Persons API. Create it in PostHog under Account Settings > Personal API Keys. For person-deletion mode, the key must be scoped to allow person deletion (the person:write scope).

Add destination

Use a sandbox to configure a destination for PostHog. Before promoting your changes, send a sample audience, and then verify the results in PostHog. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for PostHog

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for PostHog, do one of the following: Click the row in which PostHog is located. Destinations list alphabetically and you can scroll up and down the list. Search for PostHog. Start typing “pos”. The list filters to show only matching destinations. Select “PostHog”.
	Select the credential for PostHog from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Identity column The column in the query results that carries each row’s identity: the PostHog distinct_id in person-properties and events modes, the group key in group-properties mode, or the person to delete in person-deletion mode. This is always identity_value — your query must return a column with that exact name. PostHog host Which PostHog deployment this destination sends to: us (the default) or eu for PostHog Cloud, or self-hosted for a customer-hosted PostHog instance. When this is set to self-hosted, the Self-hosted URL setting is required. Self-hosted URL The base URL of your self-hosted PostHog instance — for example https://posthog.example.com. Required when PostHog host is self-hosted, and ignored otherwise. If PostHog host is self-hosted and this is left blank, the run fails. Set-once properties Applies to person-properties mode only. A comma-separated list of column names to write with PostHog’s $set_once semantics — written once and never overwritten — instead of the default $set, which overwrites on every run. Leave it blank to write every non-identity column with $set. A name that is not a column in the query results, or the identity column itself, fails the run before any data is sent. Hashed properties Applies to person-properties and group-properties modes. A comma-separated list of column names to SHA-256 hash (trimmed and lowercased) before sending. Leave it blank to send every column as-is. PostHog stores properties as literal, queryable values, so hash a column only when your own policy requires it — a hashed value can no longer be searched or filtered in PostHog. A name that is not a column in the query results, or the identity column itself, fails the run before any data is sent.
	After configuring this destination users may use orchestrations to send query results PostHog.
	Validate the audience with PostHog by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by PostHog. Send the sample audience to PostHog and verify the sample audience is correct in PostHog. Make adjustments if necessary. Only send full audiences after validation is complete.

Data validation

Amperity sends every row in the query results, except for rows it cannot build a valid request for. A row is skipped and reported as failed, and the run continues, when any of the following is true:

• The identity_value column is empty for that row, in any write mode.

• The write mode is events and the Event name column is empty for that row.

• PostHog rejects the batch that row belongs to as malformed. PostHog validates a batch as a whole, so one bad value — such as a blank identity — fails every row in that batch, not only the offending row.

Skipped rows are reported in the destination’s run details. In events mode, a row with an empty Timestamp column value is not skipped: PostHog records that event at ingest time instead of its true event time. In person-deletion mode, an identity that PostHog does not recognize — already deleted, or never present — is reported as succeeded, because the deletion is already satisfied.

Some conditions stop the entire run instead of failing individual rows, and are caught before any data is sent:

• The query results have no identity_value column.

• Set-once properties or Hashed properties names a column that is not in the query results, or names the identity column itself.

• The write mode is events and the Event name column or Timestamp column is missing from the query results.

• A required mode setting is not set — Group type in group-properties mode, or Event name column or Timestamp column in events mode.

• PostHog host is self-hosted but no Self-hosted URL is set.

A run also stops when PostHog rejects the credentials — a missing, invalid, or insufficiently scoped key — or when the configured PostHog host or Self-hosted URL is not valid. Rate-limit responses and transient PostHog server errors are retried automatically with backoff; if they persist after retries, the affected rows are reported as failed.

Note

If a single row carries more data than fits in one request, the run stops with an error. Unlike the conditions above, this is found while the query results are being sent — not before — so on a large send, some batches may already have reached PostHog before the run stops.