Skip to content
RoutingCatRoutingCatRoutingCat Docs

PostHog

RoutingCat works beside PostHog in two ways. It puts the visitor id and the variants each page shows on your PostHog events, so your PostHog data splits by variant. And it can take a conversion your site already captures in PostHog, so you never track it twice.

Put the variants on PostHog’s events

Each event gets rc_vid, the visitor id, and one rc_<page>_<slot> property per slot the page shows, holding its variant’s key, such as rc_home_hero set to learns.

The properties need no setup. Once a page has shown, the tracker that <RoutingCat /> adds to your layout registers them with your PostHog as super properties, for every later event, and again for each routed page Astro’s client router shows, once your site has initialized PostHog. It takes the first PostHog it finds:

  1. the client your posthog option names, for a site whose client lives in a module of its own, that module’s default export: routingcat({ posthog: './src/lib/posthog.ts' }) in astro.config. Without the option, posthog-js’s own instance, which your build loads from npm when your project depends on posthog-js;
  2. window.posthog, where PostHog’s HTML snippet puts it.

It waits up to ten seconds for a PostHog that loads after the page. In development, it registers nothing.

One line in posthog.init covers each page view’s first events. PostHog captures a page load’s $pageview right after init, and a client navigation’s at the address change, both before the page has shown. In the <script> that initializes PostHog from posthog-js, import the hook with import { routingcatProperties } from 'routingcat/tracker', and add before_send: routingcatProperties to posthog.init’s options: it adds the properties to every event as it leaves.

  • An existing before_send: make it an array with routingcatProperties last. posthog-js runs the hooks in order.
  • A client navigation’s $pageview gets the new page’s slots only once they show; it carries rc_vid all the same.
  • In development, the hook adds nothing.

PostHog from its HTML snippet can’t import the line, so each page view’s first events go without the properties, though every later event has them; on a visitor’s first page, those first events carry no rc_vid either. Moving PostHog to posthog-js from npm, initialized in a <script> as above, fixes it.

Take conversions from PostHog

When an outcome is an event your site already captures in PostHog, such as posthog.capture('waitlist_joined'), forward it to RoutingCat with a PostHog webhook destination rather than adding a track: one capture, counted once. The destination:

  • matches that event alone, on your production hosts through its $host property, so events from development and previews stay out;
  • posts to https://ingest.routingcat.com/v1/events, with your production server events key, from npx routingcat keys server, as a bearer token;
  • sends the event under PostHog’s name for it, with PostHog’s uuid as its id, its rc_vid property as the visitor, and "source": "posthog".

Declare the outcome in routingcat.config.ts under PostHog’s name for the event, or doctor reports an undeclared name.

Here is the destination as PostHog’s API takes it, for an example app’s contact_sales on its one production host. Change the event, the hosts and the key:

{
  "type": "destination",
  "template_id": "template-webhook",
  "name": "RoutingCat: contact_sales",
  "description": "Forwards contact_sales to RoutingCat's events endpoint, as RoutingCat's PostHog recipe sets it up.",
  "enabled": true,
  "filters": {
    "source": "events",
    "events": [{ "id": "contact_sales", "name": "contact_sales", "type": "events", "order": 0 }],
    "properties": [
      {
        "key": "$host",
        "value": ["routingcat-example.vercel.app"],
        "operator": "exact",
        "type": "event"
      }
    ],
    "filter_test_accounts": false
  },
  "inputs": {
    "url": { "value": "https://ingest.routingcat.com/v1/events" },
    "method": { "value": "POST" },
    "headers": {
      "value": { "Content-Type": "application/json", "Authorization": "Bearer sk_…" }
    },
    "body": {
      "value": {
        "name": "{event.event}",
        "id": "{event.uuid}",
        "visitor_id": "{event.properties.rc_vid}",
        "occurred_at": "{event.timestamp}",
        "source": "posthog"
      }
    },
    "debug": { "value": false }
  }
}

Create it whichever way your session allows:

  • Through PostHog’s API, with a personal API key holding hog_function:write on the project: post that body to https://us.posthog.com/api/projects/<project id>/hog_functions/, or eu.posthog.com on PostHog’s EU cloud.
  • Through PostHog’s MCP server, if your agent has it connected, with the same fields.
  • By hand, in about two minutes, as the steps below show.

To add it by hand, in your PostHog project:

  1. Open Data pipelines, choose New, then Destination, and create an “HTTP Webhook”.
  2. Name it, such as RoutingCat: waitlist_joined.
  3. Set the webhook URL to https://ingest.routingcat.com/v1/events, and the method to POST.
  4. Replace the JSON body with the body value above.
  5. Add the headers Content-Type: application/json, and Authorization: Bearer followed by the server events key.
  6. Filter on the event alone, and on the event property $host equal to your production hosts, with “Filter out internal and test users” off.
  7. Choose Create & enable. Skip the page’s test: it sends a sample event, which RoutingCat would record as real.

The destination takes the visitor from the event’s rc_vid, so an event captured before its page has shown needs the before_send line; without it, the conversion arrives with no key. PostHog delivers the event on its own terms: it retries a failing destination a few times before setting it aside, and posthog-js loses events to ad blockers unless you route PostHog through your own domain, as PostHog’s guide shows.

Know who can read the key

Anyone who can open your PostHog project’s destinations can read the server events key in the destination’s settings. That key only writes events and identity links for its site and environment, so a leak allows false conversions, never reads. npx routingcat keys server --rotate replaces it, and the old key keeps working for 24 hours, time to update the destination’s header. Access and keys covers every key.

Don’t use PostHog’s distinct_id as a visitor or account id: posthog-js writes it in the browser, and changes it at identify and reset.

Next