---
title: PostHog
---
# PostHog

Events can be sent to [PostHog](https://posthog.com) using the `postHog` sink type. Svix sends each batch of events to PostHog's [`/batch/` capture endpoint](https://posthog.com/docs/api/capture).

Like all Sinks, PostHog sinks can be created in the Stream Portal...

![PostHog-Create](/img/stream/posthog-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "postHog",
  "config": {
    "domain": "https://us.i.posthog.com",
    "projectToken": "phc_*******"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 100,
  "maxWaitSecs": 10,
  "eventTypes": [],
  "metadata": {}
}'
```

- `domain` — your PostHog ingestion domain. This is `https://us.i.posthog.com` for US Cloud, `https://eu.i.posthog.com` for EU Cloud, or your own domain for self-hosted instances. Note the `.i.` in the Cloud hosts — `us.posthog.com` and `eu.posthog.com` are different, private endpoints and won't work here.
- `projectToken` — your PostHog project API key. Svix sends it as the `api_key` field in the body of each request.

<Callout type="info">
PostHog sinks require a transformation. The transformation is what builds the PostHog event batch, and in particular it's where you set each event's `distinctId`. PostHog uses `distinctId` to attribute events to a person and rejects events that don't have one, so it can't be left unset.
</Callout>

If every event in a batch is timestamped more than 48 hours in the past, Svix sends the batch with PostHog's `historical_migration` flag set. This keeps backfills (for example, after a sink has been disabled and re-enabled) from tripping PostHog's [spike detection](https://posthog.com/docs/billing/spike-detection). You don't need to configure anything for this to happen.

# Transformations

By default, all `postHog` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The event payload (string or JSON).
 * @param input.events[].eventType - The event type (string).
 * @param input.events[].createdAt - The ISO 8601 timestamp the event was ingested at (string).
 *
 * @returns Object containing the batch of events sent to PostHog's /batch/ endpoint.
 * @returns returns.batch - An array of PostHog events (https://posthog.com/docs/data/events).
 * @returns returns.batch[].event - The name of the event sent to PostHog.
 * @returns returns.batch[].distinctId - REQUIRED. The unique identifier of the person the event
 *                                       belongs to. It cannot be inferred from the event, so you
 *                                       must set it, usually from a field in the payload. PostHog
 *                                       rejects events that have no distinctId.
 * @returns returns.batch[].timestamp - An optional ISO 8601 timestamp for the event. If omitted, PostHog uses the time it receives the event.
 * @returns returns.batch[].properties - A map of properties associated with the event (https://posthog.com/docs/data/events#event-properties).
 */
function handler(input) {
  const batch = input.events.map((event) => ({
    event: event.eventType,
    // REQUIRED. PostHog uses distinctId to attribute events to a person and rejects events that
    // have none. Replace this with a value from your payload.
    distinctId: undefined,
    timestamp: event.createdAt,
    properties: event.payload,
  }));

  return { batch };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

The transformation maps each Svix event onto a [PostHog event](https://posthog.com/docs/data/events). Most of the fields map over cleanly — `event` from the event type, `timestamp` from when the event was ingested, and `properties` from the payload. The one field you have to supply yourself is `distinctId`, since it's specific to how you identify people in PostHog.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.signed_up",
                "payload": "{\"userId\": \"usr_123\", \"plan\": \"pro\"}"
            },
            {
                "eventType": "user.signed_up",
                "payload": "{\"userId\": \"usr_456\", \"plan\": \"free\"}"
            }
        ]
    }'
```

A transformation that sets `distinctId` from the payload's `userId`:

```JavaScript
function handler(input) {
  const batch = input.events.map((event) => ({
    event: event.eventType,
    distinctId: event.payload.userId,
    timestamp: event.createdAt,
    properties: event.payload,
  }));

  return { batch };
}
```

would result in the following request being made to PostHog's `/batch/` endpoint:

```json
{
  "api_key": "phc_*******",
  "batch": [
    {
      "event": "user.signed_up",
      "distinct_id": "usr_123",
      "timestamp": "2025-07-21T14:23:17.861Z",
      "properties": { "userId": "usr_123", "plan": "pro" }
    },
    {
      "event": "user.signed_up",
      "distinct_id": "usr_456",
      "timestamp": "2025-07-21T14:23:19.204Z",
      "properties": { "userId": "usr_456", "plan": "free" }
    }
  ]
}
```

These events would subsequently be visible in your PostHog dashboard.

![PostHog-Create](/img/stream/posthog-dashboard.png)
