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 app 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 oneclick.

The super properties need no setup. Once a page has shown, <RoutingCat /> registers them with your PostHog for every later event:

when your project depends on posthog-js, withRoutingCat() hands it posthog-js’s own instance;
when PostHog comes from its HTML snippet, window.posthog works as it is.

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 when the address changes, both before the page has shown. before_send: routingcatProperties adds the properties to every event as it leaves:

// PostHog, installed as its guide for the Next.js App Router does: posthog-js's own instance,
// initialized before hydration. withRoutingCat() finds posthog-js among the dependencies and hands this
// instance to <RoutingCat />, which registers the visitor id and the live variants as super properties
// at each page view's render beacon. PostHog captures a page view's $pageview before that, so
// `before_send` takes routingcatProperties, the line the skill adds: it puts them on every event as it
// leaves. Without a project key, as in development without one, PostHog stays off.
import posthog from 'posthog-js'
import { routingcatProperties } from 'routingcat/next'

const key = process.env.NEXT_PUBLIC_POSTHOG_KEY
if (key) {
  posthog.init(key, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    defaults: '2026-05-30',
    before_send: routingcatProperties,
  })
}

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, and in a build without RoutingCat’s key, 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. Moving PostHog to posthog-js from npm, initialized in instrumentation-client.ts as above, fixes it.

An app that builds its own PostHog client, rather than initializing posthog-js’s own instance, assigns that client to window.posthog in the browser code that creates it, and adds the line to the client’s options.

Take conversions from PostHog

When an outcome is an event your app 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 the 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:

Open Data pipelines, choose New, then Destination, and create an “HTTP Webhook”.
Name it, such as RoutingCat: waitlist_joined.
Set the webhook URL to https://ingest.routingcat.com/v1/events, and the method to POST.
Replace the JSON body with the body value above.
Add the headers Content-Type: application/json, and Authorization: Bearer followed by the server events key.
Filter on the event alone, and on the event property $host equal to your production hosts, with “Filter out internal and test users” off.
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.