Skip to main content
Ask your AI

PostHog

Server Source code Package

Server-side event delivery to PostHog for product analytics, identity resolution, and group analytics via the official posthog-node SDK.

Where this fits

PostHog is a server destination in the walkerOS flow:

Sends events server-side to PostHog's ingestion API, translating walkerOS events into `capture`, `identify`, and `groupIdentify` calls with full control over identity and group resolution.

Installation​

npm install @walkeros/collector @walkeros/server-destination-posthog
import { startFlow } from '@walkeros/collector';
import destinationPosthog from '@walkeros/server-destination-posthog';

await startFlow({
  destinations: {
    posthog: {
      code: destinationPosthog,
      config: {
        settings: {
          apiKey: process.env.POSTHOG_API_KEY,
        },
      },
    },
  },
});

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
apiKey*stringPostHog project API key (starts with "phc_"). Find it in PostHog project settings.
hoststringPostHog API host. Defaults to https://us.i.posthog.com. Use https://eu.i.posthog.com for EU or your self-hosted URL.
flushAtnumberCalls the SDK queues before it starts a send on its own. Each push and each config.batch batch flushes the SDK and waits for the answer either way. Default: 20.
flushIntervalnumberMilliseconds after which the SDK sends calls still queued on its own. Each push and each config.batch batch flushes the SDK either way. Default: 10000.
personalApiKeystringPersonal API key (phx_...). With it the SDK polls feature flag definitions; this destination evaluates no flags and attaches none to its events.
featureFlagsPollingIntervalnumberMilliseconds between feature flag definition polls, with personalApiKey set. This destination evaluates no flags. Default: 30000.
disableGeoipbooleanDisable GeoIP lookups for every event. Default: true, the SDK default.
disableCompressionbooleanSend requests uncompressed (no gzip). Default: false.
requestTimeoutnumberMilliseconds before a request to PostHog times out. Default: a quarter of config.timeout (2500 at the 10 s default). A value set here wins.
fetchRetryCountnumberRetries of a failed request to PostHog. Default: 2, which with the default timeout and delay ends within config.timeout. A value set here wins.
fetchRetryDelaynumberMilliseconds between retries of a failed request. Default: a tenth of config.timeout (1000 at the 10 s default). A value set here wins.
debugbooleanEnable PostHog SDK debug logging. Default: false.
disabledbooleanDisable the PostHog client: nothing is sent. Default: false.
identifyanywalkerOS mapping value resolving to an identity object. Keys: distinctId, $set, $set_once. Resolved on every push (server is stateless).
groupanywalkerOS mapping value resolving to a group object. Keys: type, key, properties. Resolved on every push.
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
identifyanyPer-event identity mapping. Resolves to { distinctId, $set?, $set_once? }. Fires client.identify() when $set/$set_once present.
groupanyGroup assignment. Resolves to { type, key, properties? }. Fires client.groupIdentify() when properties present, adds groups to capture().

Examples

Capture with group

With settings.group mapping type to 'company' and key to 'globals.company_id', every PostHog capture call carries the resolved group.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs",
    "company_id": "company_123"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev1700000104",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000104000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
client.capture({
  "uuid": "c6a47305-44fc-8835-b15f-3f494c1f9e20",
  "distinctId": "us3r",
  "event": "page view",
  "properties": {},
  "groups": {
    "company": "company_123"
  }
})

Capture with include

With include: ['data', 'globals'] in the destination config, the data and globals sections are flattened into prefixed PostHog event properties.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev1700000101",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000101000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
client.capture({
  "uuid": "a5a5ede9-4f3b-85f4-b30f-3da8773fabfa",
  "distinctId": "us3r",
  "event": "order complete",
  "properties": {
    "data_id": "0rd3r1d",
    "data_currency": "EUR",
    "data_value": 462,
    "data_tax": 73.76,
    "data_shipping": 5.22,
    "data_total": 467.22,
    "globals_pagegroup": "shop"
  }
})

Consent granted

With consent: { analytics: true } in the destination config, a walker consent command that grants analytics calls client.enable on the PostHog client.

Event
{
  "analytics": true
}
Out
client.enable()

Consent revoked

With consent: { analytics: true } in the destination config, revoking analytics consent after a grant calls client.disable on the PostHog client.

Event
{
  "analytics": false
}
Out
client.enable();

client.disable()

Default capture

A walker event becomes a PostHog capture call with the user id as distinctId and no extra properties.

Event
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "ev1700000100",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
client.capture({
  "uuid": "b8a7f21f-1a9f-8aa7-8480-8d16fb64c44c",
  "distinctId": "us3r",
  "event": "product view",
  "properties": {}
})

Group identify

A company update fires PostHog groupIdentify with group type, key, and associated group properties.

Event
{
  "name": "company update",
  "data": {
    "company_id": "company_123",
    "company_name": "Acme",
    "plan": "enterprise"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "b22796ab4d099bb1",
  "trigger": "test",
  "entity": "company",
  "action": "update",
  "timestamp": 1700000103000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "group": {
      "map": {
        "type": {
          "value": "company"
        },
        "key": "data.company_id",
        "properties": {
          "map": {
            "name": "data.company_name",
            "plan": "data.plan"
          }
        }
      }
    }
  }
}
Out
client.groupIdentify({
  "groupType": "company",
  "groupKey": "company_123",
  "properties": {
    "name": "Acme",
    "plan": "enterprise"
  }
})

Identify with $set

A user login fires PostHog identify with $set and $set_once person properties and skips the capture.

Event
{
  "name": "user login",
  "data": {
    "user_id": "new-user-123",
    "email": "user@acme.com",
    "plan": "premium"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "377f25e2b1a89f56",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000102000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "distinctId": "data.user_id",
        "$set": {
          "map": {
            "email": "data.email",
            "plan": "data.plan"
          }
        },
        "$set_once": {
          "map": {
            "first_login": "timestamp"
          }
        }
      }
    }
  }
}
Out
client.identify({
  "distinctId": "new-user-123",
  "properties": {
    "$set": {
      "email": "user@acme.com",
      "plan": "premium"
    },
    "$set_once": {
      "first_login": 1700000102000
    }
  }
})

Identity​

Without settings.identify the distinctId is the event's user.id, then user.hash, then user.session. An event without any of them is sent with the distinctId anonymous, so all such events share one distinct id.

Batching and delivery​

This destination batches by default: config.batch sends a batch at 20 events, 10 seconds after the last event, or 30 seconds after the first, whichever comes first, and each event keeps its own outcome. Set config.batch: { size: 1 } to send each event at once. How batching, retries, deduplication and acknowledgement work for the server SDK destinations is described in Server SDK destinations.

The quickstart sets no config.consent, so PostHog receives every event and a walker consent command changes nothing. Add consent: { analytics: true } to config, next to settings, to send only with analytics consent (consent management): a revocation then calls client.disable() and a grant client.enable(). Events still waiting in the batch at a revocation are dropped by the disabled client and still count as delivered, with no ERROR line and no failed count.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)