PostHog CI Integration

Overview

Set up CI/CD pipelines for PostHog integrations. Covers mocked unit tests (no API key needed), integration tests against a PostHog dev project, and deployment annotations that mark releases in your PostHog timeline.

Prerequisites

• GitHub repository with Actions enabled
• PostHog dev project API key for integration tests
• PostHog personal API key for deployment annotations
• npm/pnpm project with vitest or jest

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Configure GitHub Secrets

set -euo pipefail
# Project key for integration tests (phc_... from dev project)
gh secret set POSTHOG_TEST_KEY --body "phc_dev_project_key"

# Personal key for deployment annotations (phx_...)
gh secret set POSTHOG_PERSONAL_API_KEY --body "phx_your_personal_key"

# Project ID for annotations
gh secret set POSTHOG_PROJECT_ID --body "12345"

Step 2: GitHub Actions Workflow

# .github/workflows/posthog-tests.yml
name: PostHog Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
        # Unit tests use mocked PostHog — no API key needed

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: unit-tests
    env:
      NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.POSTHOG_TEST_KEY }}
      POSTHOG_HOST: https://us.i.posthog.com
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run test:integration
        timeout-minutes: 5

  annotate-deploy:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: integration-tests
    steps:
      - name: Create PostHog annotation
        env:
          POSTHOG_PERSONAL_API_KEY: ${{ secrets.POSTHOG_PERSONAL_API_KEY }}
          POSTHOG_PROJECT_ID: ${{ secrets.POSTHOG_PROJECT_ID }}
        run: |
          curl -X POST "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/annotations/" \
            -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
            -H "Content-T…

PostHog Common Errors

Overview

Diagnosis and solutions for the most common PostHog integration errors. Covers event capture failures, authentication issues, feature flag problems, identity fragmentation, and SDK initialization errors.

Prerequisites

• PostHog SDK installed (posthog-js or posthog-node)
• Access to browser console or server logs
• PostHog project API key (phc_...) available

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Error 1: Events Not Appearing in Dashboard

Symptoms: posthog.capture() calls execute without error but events never show in PostHog Activity tab.

Diagnoses and fixes:

// Problem A: Not flushing in serverless/scripts
// posthog-node queues events — they're lost if process exits before flush
const posthog = new PostHog('phc_...');
posthog.capture({ distinctId: 'user-1', event: 'test' });
// FIX: Always flush before exit
await posthog.shutdown(); // or await posthog.flush()

// Problem B: Wrong API host
posthog.init('phc_...', {
  api_host: 'https://app.posthog.com', // WRONG — this is the UI
});
// FIX: Use the ingest endpoint
posthog.init('phc_...', {
  api_host: 'https://us.i.posthog.com', // CORRECT for US Cloud
  // api_host: 'https://eu.i.posthog.com', // For EU Cloud
});

// Problem C: Ad blocker blocking posthog-js requests
// FIX: Set up a reverse proxy (see posthog-sdk-patterns)
// next.config.js rewrites: /ingest/* → us.i.posthog.com/*
// Then: posthog.init('phc_...', { api_host: '/ingest' });

Error 2: Feature Flag Returns undefined or Wrong Value

// Problem: Checking flag before flags are loaded
const value = posthog.isFeatureEnabled('my-flag'); // undefined — flags not ready

// FIX: Wait for flags to load
posthog.onFeatureFlags(() => {
  const value = posthog.isFeatureEnabled('my-flag'); // Now has correct value
});

// Problem (server): no feature flags secure key, so local definitions are unavailable
const ph = new PostHog('phc_...');
const flag = await ph.getFeatureFlag('my-flag', 'user-1'); // Slow, may fail

// FIX: Pass the server-only feature flags secure key through the SDK's option
const ph = new PostHog('phc_...', {
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
});
// Now evaluates locally — faster and more reliable

Error 3: 401 Unauthorized on API Calls

set -euo pipefail
# Symptom: 401 when calling …

PostHog Core Workflow A — Product Analytics

Overview

Primary PostHog workflow covering event capture, user identification, group analytics, and person properties. This is the foundation for all PostHog analytics: capturing what users do, linking events to identified users, and grouping users by company/team for B2B analytics.

Prerequisites

• Completed posthog-install-auth setup
• posthog-js (browser) and/or posthog-node (server) installed
• Project API key (phc_...) configured

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Define Event Taxonomy

// src/analytics/events.ts
// Define all events as typed constants for consistency
export const EVENTS = {
  // User lifecycle
  USER_SIGNED_UP: 'user_signed_up',
  USER_LOGGED_IN: 'user_logged_in',
  USER_ONBOARDING_COMPLETED: 'user_onboarding_completed',

  // Core product actions
  FEATURE_USED: 'feature_used',
  ITEM_CREATED: 'item_created',
  ITEM_UPDATED: 'item_updated',
  ITEM_DELETED: 'item_deleted',
  SEARCH_PERFORMED: 'search_performed',
  EXPORT_COMPLETED: 'export_completed',

  // Revenue events
  SUBSCRIPTION_STARTED: 'subscription_started',
  SUBSCRIPTION_UPGRADED: 'subscription_upgraded',
  SUBSCRIPTION_CANCELED: 'subscription_canceled',
  PAYMENT_COMPLETED: 'payment_completed',
} as const;

// Standard property schema for consistency across events
interface BaseProperties {
  source?: 'web' | 'mobile' | 'api' | 'webhook';
  plan_tier?: 'free' | 'pro' | 'enterprise';
  duration_ms?: number;
}

Step 2: Capture Events (Browser)

import posthog from 'posthog-js';
import { EVENTS } from './events';

// Custom event with properties
posthog.capture(EVENTS.ITEM_CREATED, {
  item_type: 'document',
  source: 'web',
  plan_tier: 'pro',
});

// Timed event (measure duration)
const start = performance.now();
await doExpensiveOperation();
posthog.capture(EVENTS.EXPORT_COMPLETED, {
  format: 'csv',
  row_count: 1500,
  duration_ms: Math.round(performance.now() - start),
});

// Pageview with custom properties (if capture_pageview: false)
posthog.capture('$pageview', {
  page_title: document.title,
  referrer: document.referrer,
});

Step 3: Identify Users and Set Pr…

PostHog Core Workflow B — Feature Flags & Experiments

Overview

Feature flag management, A/B experiment evaluation, and cohort analysis with PostHog. Covers boolean and multivariate flags, local evaluation for performance, experiment setup and statistical significance, and cohort creation via the API.

Prerequisites

• Completed posthog-install-auth setup
• Familiarity with posthog-core-workflow-a (event capture)
• Personal API key (phx_...) for flag management API

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Evaluate Feature Flags (Browser)

import posthog from 'posthog-js';

// Boolean flag
if (posthog.isFeatureEnabled('new-checkout-flow')) {
  renderNewCheckout();
} else {
  renderLegacyCheckout();
}

// Multivariate flag (returns string variant name)
const variant = posthog.getFeatureFlag('pricing-page-experiment');
switch (variant) {
  case 'control':
    renderOriginalPricing();
    break;
  case 'annual-first':
    renderAnnualFirstPricing();
    break;
  case 'social-proof':
    renderSocialProofPricing();
    break;
  default:
    renderOriginalPricing(); // Fallback if flag not loaded yet
}

// Get flag payload (JSON data attached to a flag variant)
const payload = posthog.getFeatureFlagPayload('banner-config');
// payload: { text: "Spring sale!", color: "#ff6b35", discount: 20 }

// React: Wait for flags to load before rendering
posthog.onFeatureFlags(() => {
  // Flags are now loaded and ready
  const enabled = posthog.isFeatureEnabled('new-feature');
  setFeatureEnabled(enabled ?? false);
});

Step 2: Evaluate Feature Flags (Server — posthog-node)

import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
  // The SDK option accepts the server-only feature flags secure API key.
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
});

// Single flag evaluation
async function checkFlag(userId: string): Promise<boolean> {
  const enabled = await posthog.isFeatureEnabled('new-api-version', userId);
  return enabled ?? false;
}

// Multivariate flag
async function getVariant(userId: string): Promise<string> {
  const variant = await posthog.getFeatureFlag('onboarding-experiment', userId, {
    personP…

PostHog Cost Tuning

Overview

Measure the live billable volume for each enabled PostHog product, trace changes to instrumentation releases, and reduce only traffic that the product owner has classified as noise or safely sampleable. Pricing, free allowances, and product entitlements are live facts; read them from the billing dashboard, pricing calculator, and approved product limits at execution time.

Prerequisites

• PostHog Cloud account with billing access
• Application instrumented with posthog-js
• Understanding of which events drive your analytics

Authentication

• Usage inspection through private query and billing APIs requires a least-privilege personal API key or OAuth token on a trusted machine.
• Event capture and browser-side filtering use only the public project token; never ship a personal or secure key to the browser.
• Read private credentials from a secret manager, redact command output before sharing it, and select the private US or EU API host that matches the project.

Live Pricing Boundary

Do not copy prices or free allowances into implementation code. Record the billing-dashboard timestamp, current product limit, projected usage, unit price from the live calculator, and the owner who approved any data-loss tradeoff. Recheck those values before applying a change.

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Step 1: Audit Current Event Volume

set -euo pipefail
# See which events consume the most quota (last 30 days)
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/query/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "kind": "HogQLQuery",
      "query": "SELECT event, count() AS total FROM events WHERE timestamp > now() - interval 30 day GROUP BY event ORDER BY total DESC LIMIT 20"
    }
  }' | jq '.results[] | {event: .[0], count: .[1]}'

Step 2: Tune Autocapture

$autocapture is often the largest event volume. Restrict it to only useful interactions.

import posthog from 'posthog-js';

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  autocapture: {
    // Only capture click and submit events (skip change, scroll, etc.)
    dom_event_allowlist: ['click', 'submit'],
    // Only capture meaningful elements
    element_allowlist: ['a', 'button', 'form', 'input[type=submit]'],
    // Only c…

PostHog Data Handling

Overview

Privacy-safe analytics with PostHog. Covers property sanitization to strip PII before events leave the browser, consent-based tracking (opt-in/opt-out), GDPR data subject access requests and deletion, and PostHog's built-in privacy controls (IP masking, session recording masking).

Prerequisites

• PostHog project with current privacy, retention, and deletion capabilities verified for its deployment model
• posthog-js and/or posthog-node installed
• Privacy policy covering analytics data collection
• Cookie consent mechanism (e.g., CookieConsent banner)

Authentication

• Browser capture uses the public project token; do not treat it as a secret or grant it private API access.
• Subject-access, export, and deletion operations use a least-privilege personal API key or OAuth token against the private regional API host.
• Load private credentials from a server-side secret manager, redact them from logs, and never expose them through client bundles or analytics properties.
• Confirm the target project ID and US or EU region before any destructive privacy operation.

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Privacy-Safe Initialization

import posthog from 'posthog-js';

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',

  // Disable autocapture to control exactly what's captured
  autocapture: false,

  // Respect browser Do Not Track setting
  respect_dnt: true,

  // Don't capture until user consents
  opt_out_capturing_by_default: false, // Set true for opt-in model

  // Sanitize ALL properties before they leave the browser
  sanitize_properties: (properties, eventName) => {
    // Remove IP address
    delete properties['$ip'];

    // Remove potentially identifying properties
    delete properties['$device_id'];

    // Redact URLs containing tokens or auth info
    if (properties['$current_url']) {
      properties['$current_url'] = properties['$current_url']
        .replace(/token=[^&]+/g, 'token=[REDACTED]')
        .replace(/key=[^&]+/g, 'key=[REDACTED]')
        .replace(/session=[^&]+/g, 'session=[REDACTED]');
    }

    // Redact referrer tokens
    if (properties['$referrer']) {
      properties['$referrer'] = properties['$referrer']
        .replace(/token=[^&]+/g, 'token=[REDACTED]');
    }

    return properties;
  }…

PostHog Debug Bundle

Overview

Collect diagnostic evidence for PostHog support tickets. Gathers SDK versions, API connectivity, feature flag status, event flow verification, and redacted configuration. All secrets are automatically redacted.

Prerequisites

• PostHog SDK installed in project
• Access to environment variables
• curl and jq available

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Step 1: Run Full Diagnostic Script

#!/bin/bash
set -euo pipefail

BUNDLE_DIR="posthog-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== PostHog Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- Environment ---
echo "--- Runtime Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'not found')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not found')" >> "$BUNDLE_DIR/summary.txt"
echo "Python: $(python3 --version 2>/dev/null || echo 'not found')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -srm)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- SDK Versions ---
echo "--- PostHog SDK Versions ---" >> "$BUNDLE_DIR/summary.txt"
npm list posthog-js posthog-node 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "No npm PostHog packages" >> "$BUNDLE_DIR/summary.txt"
pip3 show posthog 2>/dev/null | grep -E "Name|Version" >> "$BUNDLE_DIR/summary.txt" || true
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- API Connectivity ---
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "US Cloud ingest: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" https://us.i.posthog.com/healthz >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "" >> "$BUNDLE_DIR/summary.txt"
echo -n "EU Cloud ingest: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" https://eu.i.posthog.com/healthz >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "" >> "$BUNDLE_DIR/summary.txt"…

PostHog Deploy Integration

Overview

Ship an application's PostHog integration with regional routing, a supported reverse proxy, server-side flushing, validation evidence, and an instrumentation rollback. This workflow deploys the application integration; it does not present open-source self-hosting as a supported production PostHog service.

Prerequisites

• PostHog project API key (phc_...)
• A feature flags secure API key only when server-side local evaluation is required
• A scoped private-API credential only when deployment annotations are required
• Platform CLI installed (vercel, fly, or gcloud)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass. Use the vercel, fly, or gcloud Bash allowance only for the deployment platform actually selected by the user.

Step 1: Next.js + Vercel Deployment

set -euo pipefail
# Set environment variables in Vercel
vercel env add NEXT_PUBLIC_POSTHOG_KEY production     # phc_... (public)
vercel env add NEXT_PUBLIC_POSTHOG_HOST production    # /ingest (if using proxy)
vercel env add POSTHOG_FEATURE_FLAGS_SECURE_API_KEY production # only for local evaluation
vercel env add POSTHOG_PERSONAL_API_KEY production    # only for scoped private API automation
vercel env add POSTHOG_PROJECT_ID production          # Project ID number

// next.config.js — Reverse proxy to bypass ad blockers
module.exports = {
  async rewrites() {
    return [
      {
        source: '/ingest/static/:path*',
        destination: 'https://us-assets.i.posthog.com/static/:path*',
      },
      {
        source: '/ingest/:path*',
        destination: 'https://us.i.posthog.com/:path*',
      },
    ];
  },
};

// app/providers.tsx — Client-side PostHog with proxy
'use client';
import posthog from 'posthog-js';
import { PostHogProvider } from 'posthog-js/react';
import { useEffect } from 'react';

export function PHProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      api_host: '/ingest', // Routes through your domain's reverse proxy
      capture_pageview: false, // Handle manually in App Router
      capture_pageleave: true,
    });
  }, []);

  return <PostHogProvider client={posthog}>{children}</PostHogProvider>;
}

Step 2: Server-Side Capture in Vercel Edge Funct…

PostHog Enterprise RBAC

Overview

PostHog access control uses a three-level hierarchy: Organization > Project > Resource. Organizations contain multiple projects (e.g., production, staging), and each project has its own data, feature flags, and dashboards. Members are assigned roles at the organization level and can be restricted to specific projects.

Prerequisites

• PostHog Cloud organization with the required RBAC, SSO, and audit-log entitlements confirmed from the live plan
• Organization admin role
• Multiple projects configured (one per environment)

Access Control Model

Member Roles:

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Set Up Project-Level Access

set -euo pipefail
# Create a production project with access control
curl -X POST "https://us.posthog.com/api/organizations/$ORG_ID/projects/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "access_control": true}'

# Add a member to a specific project (level 1 = Member, 8 = Admin)
curl -X POST "https://us.posthog.com/api/projects/$PROD_PROJECT_ID/members/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "USER_UUID", "level": 1}'

# List current project members
curl "https://us.posthog.com/api/projects/$PROD_PROJECT_ID/members/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | \
  jq '.results[] | {email: .user.email, level, joined_at}'

Step 2: Create Scoped API Keys

set -euo pipefail
# Read-…

PostHog Hello World

Overview

Minimal working examples demonstrating the three core PostHog operations: capturing events, identifying users, and evaluating feature flags. Covers both browser (posthog-js) and server (posthog-node) SDKs.

Prerequisites

• Completed posthog-install-auth setup
• Project API key (phc_...) configured
• posthog-js and/or posthog-node installed

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Capture Your First Event (Node.js)

// hello-posthog.ts
import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
});

async function main() {
  // 1. Capture a custom event
  posthog.capture({
    distinctId: 'user-123',
    event: 'hello_posthog',
    properties: {
      greeting: 'Hello from posthog-node!',
      source: 'hello-world-skill',
      timestamp: new Date().toISOString(),
    },
  });
  console.log('Event captured: hello_posthog');

  // 2. Identify a user with properties
  posthog.identify({
    distinctId: 'user-123',
    properties: {
      email: 'dev@example.com',
      name: 'Dev User',
      plan: 'free',
    },
  });
  console.log('User identified: user-123');

  // 3. Check a feature flag
  const flagValue = await posthog.getFeatureFlag('my-feature-flag', 'user-123');
  console.log(`Feature flag "my-feature-flag": ${flagValue}`);

  // 4. Flush and shutdown (required in scripts/serverless)
  await posthog.shutdown();
  console.log('Done — check app.posthog.com Activity tab');
}

main().catch(console.error);

Step 2: Browser Hello World (posthog-js)

// In a React component or vanilla JS
import posthog from 'posthog-js';

// Initialize (call once at app startup)
posthog.init('phc_your_project_key', {
  api_host: 'https://us.i.posthog.com',
  loaded: () => console.log('PostHog loaded'),
});

// Capture a custom event
posthog.capture('button_clicked', {
  button_name: 'signup',
  page: window.location.pathname,
});

// Identify the user after login
posthog.identify('user-123', {
  email: 'user@example.com',
  plan: 'pro',
});

// Check a feature flag
if (posthog.isFeatureEnabled('new-checkout')) {
  console.log('New checkout flow is enabled');
}

// Associate …

PostHog Incident Runbook

Overview

Rapid incident response for PostHog integration failures. PostHog Cloud has its own status page (status.posthog.com) — the first step is always determining whether the issue is PostHog-side or your integration.

Prerequisites

• The affected service, deployment window, and PostHog region are known.
• Read-only evidence is preferred; production write probes require explicit authorization.
• A safe application fallback exists for analytics and flag failures.

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Follow the triage sequence below. Stop when evidence identifies a failed boundary; do not continue mutating unrelated layers.

Severity Levels

Quick Triage (Run First)

set -euo pipefail
: "${POSTHOG_PUBLIC_HOST:?Set the US or EU ingestion host for this project}"
: "${POSTHOG_PRIVATE_HOST:?Set the matching US or EU private API host}"

# 1. Check PostHog's status page and the selected regional ingestion host.
curl -fsSI https://status.posthog.com/ | head -n 1
curl -sf -o /dev/null -w "Regional health: %{http_code}\n" \
  "$POSTHOG_PUBLIC_HOST/healthz"

# 2. Verify private API access without changing project data.
if [ -n "${POSTHOG_PERSONAL_API_KEY:-}" ]; then
  curl -sf -o /dev/null -w "Private API: %{http_code}\n" \
    "$POSTHOG_PRIVATE_HOST/api/projects/" \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY"
fi

# 3. Check the application's own health and recent delivery telemetry.
curl -sf -o /dev/null -w "Application health: %{http_code}\n" \
  "${APPLICATION_HEALTH_URL:?Set the affected service health URL}"

Do not use an event capture as the default health check: it writes project data, and an HTTP 200 only confirms receipt and payload shape, not successful ingestion. If the incident commander explicitly authorizes a production write probe, use a named synthetic event and distinct ID, record the approval and timestamp, inspect …

PostHog Install & Auth

Overview

Install PostHog SDKs and configure authentication. PostHog uses two key types: Project API Key (phc_...) for event capture (public, safe for frontend) and Personal API Key (phx_...) for private API endpoints (never expose to clients).

Prerequisites

• Node.js 20+ or Python 3.10+
• PostHog account at app.posthog.com
• Project API key from Project Settings > Project API Key
• Personal API key from Settings > Personal API Keys (for server-side admin)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Install the SDK

set -euo pipefail
# Browser SDK (posthog-js)
npm install posthog-js

# Node.js server SDK (posthog-node)
npm install posthog-node

# Python SDK
pip install posthog

Step 2: Configure Environment Variables

# .env (add to .gitignore — never commit)
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key    # Safe for frontend
POSTHOG_HOST=https://us.i.posthog.com               # US Cloud (or eu.i.posthog.com)
POSTHOG_PERSONAL_API_KEY=phx_your_personal_key      # Server-only, never expose
POSTHOG_FEATURE_FLAGS_SECURE_API_KEY=your_project_specific_secure_key # Server-side only
POSTHOG_PROJECT_ID=12345                             # From project URL

Step 3: Initialize Browser SDK (posthog-js)

// lib/posthog.ts
import posthog from 'posthog-js';

export function initPostHog() {
  if (typeof window === 'undefined') return;

  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
    capture_pageview: true,        // Auto-capture $pageview
    capture_pageleave: true,       // Auto-capture $pageleave
    autocapture: true,             // Auto-capture clicks, inputs, form submits
    persistence: 'localStorage+cookie',
    loaded: (ph) => {
      if (process.env.NODE_ENV === 'development') {
        ph.debug();  // Logs all events to console
      }
    },
  });
}

Step 4: Initialize Server SDK (posthog-node)

// lib/posthog-server.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHog(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POS…

PostHog Local Dev Loop

Overview

Set up a fast local development workflow for PostHog integrations. Covers debug mode for event inspection, mocking posthog-node for unit tests, and a dev/test PostHog project to avoid polluting production data.

Prerequisites

• Completed posthog-install-auth setup
• Node.js 20+ with npm/pnpm
• Vitest or Jest for testing
• Separate PostHog project for development (recommended)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Project Structure

my-posthog-app/
├── src/
│   ├── analytics/
│   │   ├── posthog.ts         # Singleton client
│   │   ├── events.ts          # Event taxonomy (typed constants)
│   │   └── flags.ts           # Feature flag keys
│   └── index.ts
├── tests/
│   ├── analytics.test.ts      # Unit tests with mocked PostHog
│   └── integration.test.ts    # Integration tests (real PostHog dev project)
├── .env.local                 # Dev keys (git-ignored)
├── .env.example               # Template: NEXT_PUBLIC_POSTHOG_KEY=phc_...
└── package.json

Step 2: PostHog Client with Dev Mode

// src/analytics/posthog.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHog(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
      flushAt: process.env.NODE_ENV === 'development' ? 1 : 20,
      flushInterval: process.env.NODE_ENV === 'development' ? 0 : 10000,
      // In dev, flush immediately so events appear instantly in dashboard
    });
  }
  return client;
}

export async function shutdown() {
  if (client) {
    await client.shutdown();
    client = null;
  }
}

Step 3: Browser Debug Mode

// Enable PostHog debug mode in development
import posthog from 'posthog-js';

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  loaded: (ph) => {
    if (process.env.NODE_ENV === 'development') {
      ph.debug();
      // All events logged to browser console:
      // [PostHog.js] Sending event: {"event":"$pageview","properties":{...}}
    }
  },
});

// Disable capture entirely in test environments
if (process.env.NODE_ENV === 'test') {
  posthog.opt_out_capturing();
}

Step 4: Mock PostHog fo…

PostHog Migration Deep Dive

Overview

Migrate from Google Analytics, Mixpanel, Amplitude, or Segment to PostHog using a dual-write strategy (send events to both old and new platforms) followed by gradual traffic shifting. PostHog's capture API accepts events in a format similar to Segment's track/identify calls, making migration straightforward.

Prerequisites

• A paid product analytics plan and a dedicated target project are confirmed for historical imports.
• The event taxonomy, distinct-ID map, timestamp policy, and rollback owner are approved.
• A representative sample can be validated before full ingestion.

Authentication

• Use the target project's public project token only for event capture. It is an ingestion identifier, not a secret or a credential for private APIs.
• Use a least-privilege personal API key or OAuth token for private project APIs, keep it in a secret manager, and never place it in browser code, logs, examples, or committed files.
• If server-side local feature-flag evaluation is required, use a feature flags secure API key through the SDK's personalApiKey option; do not reuse a broadly scoped personal API key.
• Select the matching US or EU host for the target project before any sample or bulk write.

Migration Types

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Event Name Mapping

Create a reviewed mapping table with source event, target event, source property, target property, source identity, target distinct ID, timestamp conversion, consent class, and owner. Reject unknown identities, empty event names, invalid timestamps, and unreviewed PII instead of silently coercing them.

Step 2: Dual-Write Adapter

Wrap the existing a…

PostHog Multi-Environment Setup

Overview

Use separate PostHog projects for each environment (dev, staging, production). This prevents dev/test events from polluting production analytics, allows different feature flag rollout percentages per environment, and lets you disable session recordings in non-production.

Prerequisites

• PostHog Cloud organization that supports the required project and feature-flag environment model
• Admin access to create multiple projects
• Deployment platform with environment variable support

Environment Strategy

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Create Separate PostHog Projects

In PostHog Cloud (app.posthog.com), create three projects:

1. myapp-development — copy the phc_... project API key
2. myapp-staging — copy the phc_... project API key
3. myapp-production — copy the phc_... project API key

Step 2: Environment Variables

# .env.local (development — git-ignored)
NEXT_PUBLIC_POSTHOG_KEY=phc_dev_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_PERSONAL_API_KEY=phx_your_key
POSTHOG_PROJECT_ID=11111

# .env.staging (CI/CD secrets or secret manager)
NEXT_PUBLIC_POSTHOG_KEY=phc_staging_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_PERSONAL_API_KEY=phx_your_key
POSTHOG_PROJECT_ID=22222

# Production (secret manager — never in files)
# NEXT_PUBLIC_POSTHOG_KEY=phc_prod_key_here
# POSTHOG_PROJECT_ID=33333

Step 3: Environment-Aware SDK Configuration

// config/posthog.ts
type Env = 'development' | 'staging' | 'production';

interface PostHogEnvConfig {
  apiKey: string;
  host: string;
  sessionRecording: boolean;
  recordingSampleRate: number;
  autocapture: boolean | object;
  debug: boolean;
}

function getConfig(): PostHogEnvConfig {
  const env = (process.env.NODE_ENV || 'development')…

PostHog Observability

Overview

Observe four boundaries independently: application capture attempts and failures, SDK queue and flush behavior, PostHog ingestion warnings and accepted event volume, and feature-flag cache or remote-fallback behavior. Treat every Prometheus metric below as application-owned instrumentation, not as a metric exported by PostHog.

Prerequisites

• PostHog project with personal API key (phx_...)
• Application instrumented with PostHog SDK
• Prometheus/Grafana or equivalent monitoring stack (optional)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Event Ingestion Health Check

set -euo pipefail
# Check if events are flowing (last 24 hours)
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/query/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "kind": "HogQLQuery",
      "query": "SELECT toStartOfHour(timestamp) AS hour, count() AS events FROM events WHERE timestamp > now() - interval 24 hour GROUP BY hour ORDER BY hour"
    }
  }' | jq '.results | map({hour: .[0], events: .[1]}) | .[-3:]'

Step 2: Instrument Flag Evaluation Latency

// posthog-instrumented.ts
import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
});

// Wrap flag evaluation with timing
async function getFlag(flagKey: string, userId: string): Promise<any> {
  const start = performance.now();
  const value = await posthog.getFeatureFlag(flagKey, userId);
  const durationMs = performance.now() - start;

  // Emit metrics to your monitoring system
  emitHistogram('posthog_flag_eval_duration_ms', durationMs, { flag: flagKey });
  emitCounter('posthog_flag_evals_total', 1, { flag: flagKey, result: String(value) });

  // Alert on slow evaluations (likely means local eval not configured)
  if (durationMs > 200) {
    console.warn(`[PostHog] Slow flag eval: ${flagKey} took ${durationMs.toFixed(0)}ms — inspect secure-key cache and fallback behavior`);
  }

  return value;
}

// Example: emit to Prometheus via prom-client
import { Histogram, Counter, Gauge } from 'prom-client';

const flagDuration = new Histogram({
  name: 'posthog_flag_eval_duration_ms',
  help: 'PostHog feat…

PostHog Performance Tuning

Overview

Optimize PostHog for production workloads. The biggest performance wins are: local feature flag evaluation (eliminates network calls), proper batching configuration, event sampling for high-volume apps, and efficient HogQL queries with date filters.

Prerequisites

• posthog-node and/or posthog-js installed
• Personal API key (phx_...) for local flag evaluation
• Feature flags configured (if applicable)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Enable Local Feature Flag Evaluation

With server-side local evaluation, the SDK periodically fetches flag definitions and evaluates compatible flags from its local cache. A cold cache, unsupported condition, or evaluation failure can still fall back to a remote request, so measure cache readiness and fallback behavior in the target runtime.

import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
  // Pass the server-only feature flags secure key through this SDK option.
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
  // Flag definitions are polled every 30 seconds by default
  // Adjust if you need faster flag updates:
  // featureFlagsPollingInterval: 10000, // 10 seconds
});

// With the feature flags secure key passed through personalApiKey, definitions are cached locally.
const variant = await posthog.getFeatureFlag('pricing-experiment', 'user-123', {
  personProperties: { plan: 'pro', country: 'US' },
});

// Get all flags at once (still local, still fast)
const allFlags = await posthog.getAllFlags('user-123', {
  personProperties: { plan: 'pro' },
  groupProperties: { company: { industry: 'SaaS' } },
});

Step 2: Optimize Client Batching

// Production: batch events for network efficiency
const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
  flushAt: 20,           // Send batch when 20 events accumulated (default)
  flushInterval: 10000,  // Or flush every 10 seconds (default)
  requestTimeout: 10000, // 10 second timeout per request
  maxRetries: 3,         // Retry failed sends
});

// Serverless: flush immediately (function may exit)
const serverless = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: 'https://us.i.posthog.com',
  flushAt: 1,       // Send every event immediatel…

PostHog Production Checklist

Overview

Production readiness verification for PostHog integrations. Covers SDK configuration hardening, graceful degradation when PostHog is unavailable, health check endpoints, proper shutdown hooks for serverless, and rollback procedures.

Prerequisites

• PostHog integration tested in staging
• Production PostHog project with phc_ key
• Least-privilege private API credential only for the private operations the integration actually performs
• Deployment pipeline configured

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Pre-Deployment Checklist

SDK Configuration:

• [ ] api_host set to correct region (us.i.posthog.com or eu.i.posthog.com)
• [ ] capture_pageview: false if using SPA with manual pageview tracking
• [ ] capture_pageleave: true for session duration accuracy
• [ ] Reverse proxy configured to bypass ad blockers (see posthog-sdk-patterns)
• [ ] posthog.debug() disabled in production (guarded by NODE_ENV)
• [ ] autocapture configured to exclude noisy elements

Server-Side:

• [ ] posthog.shutdown() called in SIGTERM handler and serverless function cleanup
• [ ] Feature flags secure API key is passed through personalApiKey for server-side local evaluation
• [ ] flushAt and flushInterval tuned (default 20/10s is fine for most apps)

Security:

• [ ] Personal API key (phx_) never in client bundles or NEXT_PUBLIC_ vars
• [ ] .env files in .gitignore
• [ ] Separate PostHog project per environment

Step 1: Production SDK Configuration

// lib/posthog-production.ts
import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
  flushAt: 20,
  flushInterval: 10000,
  requestTimeout: 10000,
  maxRetries: 3,
});

// Graceful shutdown
async function shutdown() {
  await posthog.shutdown();
  process.exit(0);
}
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Step 2: Graceful Degradation

// PostHog should never break your app — wrap all calls
function safeCapture(distinctId: string, event: string, properties?: R…

PostHog Rate Limits

Overview

PostHog rate limits apply to private API endpoints authenticated with a personal API key, project secret key where available, or OAuth. Public POST-only capture and flag endpoints have no PostHog request-level rate limit, but capture can still report billing limits in a successful response.

Prerequisites

• A least-privilege personal API key, project secret key where available, or OAuth token for private endpoints
• Understanding of which endpoints you call and how often
• posthog-node or direct API usage

PostHog Rate Limit Tiers

These budgets apply to the whole PostHog team, not to each key or process. Coordinate workers through a shared limiter when more than one caller uses the same endpoint class.

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Implement Exponential Backoff with Retry-After

async function postHogApiCall<T>(
  url: string,
  options: RequestInit,
  maxRetries = 5
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
        ...options.headers,
      },
    });

    if (response.ok) {
      return response.json();
    }

    if (response.status === 429)…

PostHog Reference Architecture

Overview

Production-grade architecture for PostHog analytics in a web application. Covers file structure, event taxonomy design, SDK initialization layers, feature flag management, group analytics for B2B, and data pipeline integration.

Prerequisites

• PostHog Cloud project, or an explicitly risk-accepted hobby self-hosted instance with its reduced feature and support boundaries documented
• posthog-js and posthog-node SDKs
• Next.js or React application (patterns adapt to other frameworks)

Authentication

• Browser and server capture use the public project token and the regional ingestion host.
• Private API automation uses a least-privilege personal API key or OAuth token only on trusted servers.
• Local feature-flag evaluation uses a feature flags secure API key passed through the Node SDK's personalApiKey option.
• Keep every secret in the deployment platform's secret manager; never expose private or secure keys in browser code, logs, source control, or event properties.

Architecture

┌─────────────────────────────────────────────────────┐
│  Browser (posthog-js)                                │
│  $pageview, $autocapture, custom events, identify   │
│  Feature flag evaluation, session recordings         │
└────────────┬────────────────────────────────────────┘
             │ HTTPS (direct or reverse proxy)
             ▼
┌─────────────────────────────────────────────────────┐
│  PostHog Cloud (us.i.posthog.com)                    │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Events   │  │ Feature  │  │ Session Replay    │  │
│  │ Pipeline │  │ Flags    │  │ & Recordings      │  │
│  └────┬─────┘  └────┬─────┘  └───────────────────┘  │
│       │              │                                │
│  ┌────┴──────────────┴────────────────────────────┐  │
│  │  Analytics: Trends, Funnels, Retention, Paths  │  │
│  │  HogQL (SQL), Dashboards, Cohorts              │  │
│  └────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────┐  │
│  │  CDP: Destinations (Webhook, Slack, S3, etc.)  │  │
│  └────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
             ▲
             │ posthog-node (server events, local flag eval)
┌────────────┴────────────────────────────────────────┐
│  Backend (API routes, webhooks, crons)               │
│  Server-side capture, group identify, flag eval      │
└─────────────────────────────────────────────────────┘

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries.

Step 1: Proj…

PostHog SDK Patterns

Overview

Production-ready patterns for PostHog integrations: singleton client, type-safe event capture, React hooks for feature flags, Next.js App Router provider, and Python integration patterns.

Prerequisites

• posthog-js and/or posthog-node installed
• TypeScript project with strict mode
• React/Next.js (for frontend patterns)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Singleton Server Client

// lib/posthog-server.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHogServer(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
      personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
      flushAt: 20,
      flushInterval: 10000,
    });
  }
  return client;
}

// Graceful shutdown hook
process.on('SIGTERM', async () => {
  if (client) await client.shutdown();
  process.exit(0);
});

Step 2: Type-Safe Event Capture

// lib/analytics/events.ts
type EventMap = {
  user_signed_up: { method: 'email' | 'google' | 'github' };
  feature_used: { feature_name: string; duration_ms?: number };
  subscription_started: { plan: string; interval: 'monthly' | 'annual'; mrr: number };
  item_created: { item_type: string; source: 'web' | 'api' };
  search_performed: { query: string; results_count: number };
};

export function capture<K extends keyof EventMap>(
  distinctId: string,
  event: K,
  properties: EventMap[K]
) {
  const ph = getPostHogServer();
  ph.capture({ distinctId, event, properties });
}

// Usage: fully type-checked
capture('user-123', 'subscription_started', {
  plan: 'pro',
  interval: 'annual',
  mrr: 99,
});

Step 3: React Feature Flag Hook

// hooks/useFeatureFlag.ts
'use client';
import { useEffect, useState } from 'react';
import posthog from 'posthog-js';

export function useFeatureFlag(flagKey: string): boolean | undefined {
  const [enabled, setEnabled] = useState<boolean | undefined>(undefined);

  useEffect(() => {
    // Check immediately if flags are already loaded
    const current = posthog.isFeatureEnabled(flagKey);
    if (current !== undefined) {
      setEnabled(current);
    }

    // Listen for flag updates (init…

PostHog Security Basics

Overview

Secure PostHog API key management, least-privilege access, and secret rotation. PostHog has two key types with very different security profiles: the Project API Key (phc_...) is intentionally public and safe to include in frontend bundles, while the Personal API Key (phx_...) grants admin access and must never be exposed.

Prerequisites

• PostHog account with admin access
• Understanding of environment variable management
• .gitignore configured

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project.

Step 1: Understand Key Security Profiles

# .env (NEVER commit)
NEXT_PUBLIC_POSTHOG_KEY=phc_abc123   # Safe for frontend (NEXT_PUBLIC_ prefix)
POSTHOG_PERSONAL_API_KEY=phx_xyz789  # Server-only — NEVER in frontend code
POSTHOG_PROJECT_ID=12345

# .gitignore
.env
.env.local
.env.*.local

Step 2: Create Scoped Personal API Keys

set -euo pipefail
# Create a read-only key for BI dashboards
curl -X POST "https://us.posthog.com/api/personal_api_keys/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "bi-dashboard-readonly",
    "scopes": ["insight:read", "dashboard:read", "query:read"]
  }'

# Create a key scoped to feature flags only
curl -X POST "https://us.posthog.com/api/personal_api_keys/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "feature-flag-service",
    "scopes": ["feature_flag:read", "feature_flag:write"]
  }'

Step 3: Rotate Personal API Keys

set -euo pipefail
# 1. Create new key in PostHog Settings > Personal API Keys
# 2. Update secret in your deployment platform
# Vercel:
vercel env rm POSTHOG_PERSONAL_API_KEY production
vercel env add POSTHOG_PERSONAL_API_KEY …

PostHog Upgrade & Migration

Overview

Upgrade PostHog SDKs from the versions actually locked by the target project to explicit target versions. Build the change list from current release notes and type surfaces, then prove capture, identity, consent, flags, flushing, and rollback behavior in the environments the application uses.

Prerequisites

• PostHog SDK currently installed
• Git for branching
• Test suite covering PostHog integration
• Staging environment for validation

Instructions

Tool discipline

Use Read and Grep to inspect manifests, lockfiles, initialization, and release-sensitive options before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass. Use npm, npx, pip, and git Bash commands only in the selected project and preserve the recorded rollback versions.

Step 1: Audit Current Versions

set -euo pipefail
# Check installed versions
echo "=== posthog-js ==="
npm list posthog-js 2>/dev/null || echo "Not installed"
echo "=== posthog-node ==="
npm list posthog-node 2>/dev/null || echo "Not installed"
echo "=== Python posthog ==="
pip3 show posthog 2>/dev/null | grep Version || echo "Not installed"

# Check latest available versions
echo "=== Latest available ==="
npm view posthog-js version 2>/dev/null
npm view posthog-node version 2>/dev/null

Step 2: Build the Version Delta

Read every release note between the locked and target versions, plus the current SDK reference for each configured option. Produce a small evidence table with: package, locked version, target version, runtime requirement, changed default or API, affected source locations, required test, and rollback version. Pay particular attention to browser defaults dates, autocapture and persistence, consent, replay, server flush semantics, feature-flag evaluation, and whether events attach flag properties. Do not infer compatibility from a major-version number or a remembered migration note.

Step 3: Upgrade Procedure

set -euo pipefail
# Create upgrade branch
git checkout -b upgrade/posthog-sdks

: "${POSTHOG_NODE_TARGET:?Set the reviewed posthog-node target version}"
: "${POSTHOG_JS_TARGET:?Set the reviewed posthog-js target version}"

# Install the exact reviewed versions and let the lockfile record them.
npm install "posthog-node@$POSTHOG_NODE_TARGET" "posthog-js@$POSTHOG_JS_TARGET"
# Check for type errors
npx tsc --noEmit 2>&1 | grep -i posthog || echo "No PostHog type errors"

#…

PostHog Webhooks & Events

Overview

PostHog sends webhooks via its CDP (Customer Data Platform) Destinations feature. You configure a Destination that fires when matching events are captured, sending an HTTP POST to your endpoint. This skill covers webhook destination setup, receiving and processing webhook payloads, querying events via the API, and using HogQL for custom event analysis.

Prerequisites

• PostHog project with personal API key (phx_...)
• HTTPS endpoint to receive webhooks
• Events being captured in PostHog

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Create a Webhook Destination via API

set -euo pipefail
# Create a webhook destination that fires on specific events
curl -X POST "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/pipeline_destinations/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup Notifications",
    "description": "Send webhook when user signs up",
    "config": {
      "url": "https://your-app.com/webhooks/posthog",
      "method": "POST",
      "headers": {
        "X-Webhook-Secret": "your-webhook-secret"
      },
      "body": {
        "event": "{event}",
        "distinct_id": "{distinct_id}",
        "person": "{person}",
        "properties": "{properties}",
        "timestamp": "{timestamp}"
      }
    },
    "filters": {
      "events": [
        {"id": "user_signed_up", "type": "events"},
        {"id": "subscription_started", "type": "events"}
      ]
    }
  }'

Step 2: Receive and Process Webhooks

// api/webhooks/posthog.ts
import { NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.POSTHOG_WEBHOOK_SECRET!;

// Verify webhook authenticity
function verifySignature(payload: string, signature: string): boolean {
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface PostHogWebhookPayload {
  event: string;
  distinct_id: string;
  properties: Reco…