Send events to PostHog
Forward product events into a customer's PostHog project, distinct_id mapping, person properties, native API.
What is PostHog?
PostHog is an open-source product analytics platform that many SaaS teams use to track funnels, feature flags, and session replays. As a destination, PostHog lets a customer enrich their own product analytics with events from your platform, your events appear in their PostHog instance alongside the events they emit directly. Pushrail's adapter calls PostHog's `/capture` API with the canonical event mapped into PostHog's event shape.
Why deliver events to PostHog
- Customer's product analytics get a fuller picture by including events from your platform.
- Funnel and retention analyses can span both the customer's product and yours.
- PostHog feature flags can be informed by events you emit on the customer's behalf.
- Same person model, `distinct_id` maps from `customerExternalId` so identity stays consistent.
How Pushrail delivers events to PostHog
The adapter POSTs each event to the configured PostHog instance's `/capture/` endpoint. `distinct_id` defaults to `customerExternalId`. `event` is the `eventType` (with an optional configurable prefix like `pushrail:`). The canonical `payload` and `metadata` are flattened into PostHog's `properties` object. `$insert_id` is set from `idempotencyKey` so PostHog dedups on re-sends within its window.
Auth and credentials
PostHog uses a project API key per project, Pushrail stores it encrypted at rest. The key is write-only by design (it cannot read data). Rotations happen in PostHog and are reflected in the Pushrail destination in one update. For self-hosted PostHog, customers also configure the instance URL.
Batching, retries, and replay
The adapter uses PostHog's `/batch/` endpoint with up to 100 events per batch and a 1-second flush. Transient errors (5xx, throttling) retry with exponential backoff. Permanent errors (401, 403) land in the DLQ. Replay re-sends with the same `$insert_id` so PostHog's native dedup applies, re-running a window does not inflate event counts.
Example payload
Pushrail accepts the canonical event shape on POST /v1/events. Below is the ingestion request your service makes.
{
"eventType": "order.completed",
"occurredAt": "2026-05-26T14:21:08.493Z",
"source": "billing-service",
"customerExternalId": "acct_8K2zRq",
"idempotencyKey": "order_38a91f-completed",
"correlationId": "req_4f30b2",
"payload": {
"orderId": "ord_38a91f",
"amount": 12900,
"currency": "USD",
"items": [
{ "sku": "PR-PRO-MONTHLY", "qty": 1, "price": 12900 }
]
},
"metadata": {
"tier": "pro",
"region": "us-east-1"
}
}Example configuration
The fields your customer fills in to point Pushrail at their PostHog setup.
{
"type": "POSTHOG",
"name": "Customer PostHog project",
"instanceUrl": "https://us.i.posthog.com",
"projectApiKey": "phc_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"distinctIdField": "customerExternalId",
"eventNamePrefix": "pushrail:"
}Common use cases
- Enrich a customer's PostHog with events your product emits about them.
- Span funnels across the customer's product and yours.
- Inform PostHog feature flags with signals from your platform.
- Power customer-built analytics without spinning up a warehouse.
Related destinations
Stream events directly into a customer's BigQuery dataset, table per event type or single wide table.
HMAC-signed JSON POSTs with retries, replay, and a per-attempt audit trail.
High-throughput row-shaped event delivery into a customer's ClickHouse cluster, one row per event.
Frequently asked questions
What does delivering to PostHog give my customer?
Your product's events appear in their PostHog project alongside the events they emit directly, so funnel and retention analyses can span both the customer's product and yours, and PostHog feature flags can be informed by signals you emit on their behalf.
How does Pushrail map events into PostHog?
The adapter POSTs each event to the PostHog instance's /capture/ endpoint. distinct_id defaults to customerExternalId so identity stays consistent, event is the eventType with an optional configurable prefix, and the canonical payload and metadata are flattened into PostHog's properties object.
How is authentication handled, and does it work with self-hosted PostHog?
PostHog uses a project API key, stored encrypted at rest; it is write-only by design and cannot read data. Rotations happen in PostHog and are reflected in the Pushrail destination in one update. For self-hosted PostHog, the customer also configures the instance URL.
Are replays safe for PostHog event counts?
Yes. $insert_id is set from the idempotency key, so PostHog's native dedup applies on re-sends. Transient errors (5xx, throttling) retry with exponential backoff and permanent errors (401, 403) land in the dead-letter queue, so re-running a window does not inflate event counts.