Analytics

Analytics destinations forward events to product-analytics tools where they can be charted, segmented, and joined to user behavior data. v1 supports PostHog; additional analytics destinations are tracked on the roadmap.

When to use

Pick an analytics destination when a product, growth, or data team wants the events you already emit visible in their analytics tool of choice. The classic example is forwarding billing or fulfillment events (orders, subscriptions, refunds) into the same tool the team uses for funnel analysis, so revenue events and behavior events sit in one place.

Analytics destinations are not a substitute for a warehouse or a database. They are optimized for exploration, not for long-term storage or programmatic consumption. If you need a queryable historical record, pair the analytics destination with a warehouse destination.

Auth options

PostHog uses a project API key:

• Project API key, created in PostHog under Project Settings → API Keys. The key is encrypted at rest and masked in the dashboard.
• Self-hosted PostHog, the same key shape; provide your instance's host alongside the key.

The key needs only the event:write capability. Avoid using a personal API key here, project-scoped keys give you tighter blast radius and can be rotated without affecting your own PostHog session.

Config reference

PostHog

Required: host, projectApiKey. Optional: distinctIdField (defaults to customerExternalId), eventNameField (defaults to eventType), propertiesField (defaults to payload).

{
  "type": "posthog",
  "host": "https://us.posthog.com",
  "projectApiKey": "{{secret}}",
  "distinctIdField": "customerExternalId",
  "eventNameField": "eventType",
  "propertiesField": "payload"
}

Pushrail maps the canonical event into PostHog's capture event shape:

• The canonical eventType becomes PostHog's event field.
• The canonical customerExternalId becomes PostHog's distinct_id.
• The canonical payload becomes PostHog's properties (merged with metadata: $lib, $source).
• The canonical occurredAt becomes PostHog's timestamp.

Self-hosted PostHog instances work identically, set host to your own URL.

Common patterns

Route only revenue and product events: PostHog ingestion is metered. Use a routing rule to forward only the event types analytics actually cares about (e.g., subscription.*, order.*) instead of every event your product emits.

Map customer to user, not org: PostHog's distinct_id is user-grained; if your customerExternalId is an organization id, use a transform to swap in the user id from the payload before forwarding.

Preserve occurredAt: PostHog accepts an explicit timestamp and will use it instead of the ingest time. Pushrail forwards it automatically, your historical or backfilled events land at the correct point on PostHog charts.

Verifying delivery

The delivery log shows PostHog's per-event ingestion response and the resolved distinct_id. Successful deliveries appear in PostHog's Live Events view within a few seconds; if you don't see them, the destination card's success rate metric is the first place to look.

Common failure modes: an invalid project key (401), an eventNameField that resolved to null (the source event was missing the field the mapping pointed at), or PostHog rate-limiting on a large backfill. Each shows up as a typed error in the delivery log.