Skip to main content
skill CX Codex

posthog-webhooks-events — Claude Code skill: webhooks and HogQL

posthog-webhooks-events registers PostHog webhook destinations through the API, handles the incoming payloads, and runs bounded event queries with HogQL or the private API.

MIT 1 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-webhooks-events -a claude-code
Open on GitHub

What posthog-webhooks-events does

Step one is a curl call to pipeline_destinations/ on the project API. It registers a Destination with its URL, method, headers and body template, and a filter naming the events to deliver, such as user_signed_up.

Then comes the receiving end. The sample route compares the secret header, parses the payload and sends each event to its own handler. For digging into data, the skill shows events/ lookups with limit and orderBy, plus HogQL posted to /query/ — a signup funnel grouped by referrer, feature usage split by plan.

You need a PostHog project with a phx_... personal key, an HTTPS endpoint and events already flowing in. Bash is limited to curl here, so everything gets checked by request rather than by a test run.

What it helps with

  • Register a PostHog webhook destination for chosen events
  • Verify the secret header on an incoming webhook
  • Route each PostHog event to its own handler
  • Pull recent events of one type from the private API
  • Build a signup funnel by referrer in HogQL

Example prompts for the agent

  • Create a PostHog destination that posts user_signed_up to https://your-app.com/webhooks/posthog
  • Write the webhook route with secret verification and a switch over event names
  • Query feature usage per plan with HogQL for the last 7 days

How to install posthog-webhooks-events

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-webhooks-events -a claude-code

2Manually: put the files in place

~/.claude/skills/posthog-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/posthog-webhooks-events/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about posthog-webhooks-events

How do I install posthog-webhooks-events in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-webhooks-events -a claude-code; the skill file then sits at ~/.claude/skills/posthog-webhooks-events/SKILL.md.

What does posthog-webhooks-events do?

It walks through creating a PostHog Destination via API, receiving and processing webhook payloads, and querying events with the private API or HogQL.

What do I need before using it?

A PostHog project with a phx_... personal API key, an HTTPS endpoint to receive the webhooks, and events already captured in the project.

Source text

SKILL.md · MIT
---
name: posthog-webhooks-events
description: |
  Build and verify PostHog realtime webhook destinations and bounded private-API or HogQL event queries. Use when delivering selected events to another system or investigating event data. Trigger with "PostHog webhook", "PostHog destination", or "PostHog HogQL query".
argument-hint: "[project] [destination-or-query]"
allowed-tools: Read, Write, Edit, Bash(curl:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- posthog
- webhooks
compatibility: Designed for Claude Code
---
# 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

```bash
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

```typescript
// 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: Record<string, any>;
  person: {
    properties: Record<string, any>;
  };
  timestamp: string;
}

export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('x-webhook-secret') || '';

  // Verify webhook is from PostHog
  if (WEBHOOK_SECRET && signature !== WEBHOOK_SECRET) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const payload: PostHogWebhookPayload = JSON.parse(body);

  // Route to handlers based on event type
  switch (payload.event) {
    case 'user_signed_up':
      await onUserSignup(payload);
      break;
    case 'subscription_started':
      await onSubscriptionStarted(payload);
      break;
    case 'subscription_canceled':
      await onSubscriptionCanceled(payload);
      break;
    default:
      console.log(`Unhandled PostHog event: ${payload.event}`);
  }

  return NextResponse.json({ received: true });
}

async function onUserSignup(payload: PostHogWebhookPayload) {
  const { distinct_id, properties, person } = payload;
  console.log(`New signup: ${distinct_id}`);

  // Sync to CRM
  await fetch('https://api.hubspot.com/contacts/v1/contact/', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.HUBSPOT_KEY}` },
    body: JSON.stringify({
      properties: [
        { property: 'email', value: person.properties.email },
        { property: 'posthog_id', value: distinct_id },
      ],
    }),
  });

  // Notify Slack
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    body: JSON.stringify({
      text: `New signup: ${person.properties.email || distinct_id} (${properties.source || 'unknown'})`,
    }),
  });
}

async function onSubscriptionStarted(payload: PostHogWebhookPayload) {
  console.log(`New subscription: ${payload.distinct_id}, plan: ${payload.properties.plan}`);
}

async function onSubscriptionCanceled(payload: PostHogWebhookPayload) {
  console.log(`Cancellation: ${payload.distinct_id}`);
}
```

### Step 3: Query Events via the API

```bash
set -euo pipefail
# List recent events by type
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/events/?event=user_signed_up&limit=10&orderBy=-timestamp" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | \
  jq '.results[] | {
    distinct_id,
    event,
    timestamp,
    properties: (.properties | {source, plan, referrer: ."$referrer"})
  }'

# Get events for a specific person
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/events/?distinct_id=user-123&limit=20" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | \
  jq '.results[] | {event, timestamp}'
```

### Step 4: Query Events with HogQL

```typescript
// Complex event analysis with HogQL (PostHog's SQL dialect)
async function queryPostHog(hogql: string) {
  const response = await fetch(
    `https://us.posthog.com/api/projects/${process.env.POSTHOG_PROJECT_ID}/query/`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
      },
      body: JSON.stringify({
        query: { kind: 'HogQLQuery', query: hogql },
      }),
    }
  );
  return response.json();
}

// Example: Signup funnel analysis
const funnelData = await queryPostHog(`
  SELECT
    properties.$referrer AS referrer,
    count() AS signups,
    uniq(distinct_id) AS unique_users
  FROM events
  WHERE event = 'user_signed_up'
    AND timestamp > now() - interval 30 day
  GROUP BY referrer
  ORDER BY signups DESC
  LIMIT 20
`);

// Example: Feature adoption by plan
const adoptionData = await queryPostHog(`
  SELECT
    person.properties.plan AS plan,
    properties.feature_name AS feature,
    count() AS usage_count,
    uniq(distinct_id) AS unique_users
  FROM events
  WHERE event = 'feature_used'
    AND timestamp > now() - interval 7 day
  GROUP BY plan, feature
  ORDER BY usage_count DESC
  LIMIT 50
`);
```

### Step 5: Set Up Slack Webhook Destination (UI)

PostHog has built-in Slack integration via Data Pipelines > Destinations:

1. Go to Data Pipelines > Destinations > New Destination
2. Select "Slack" or "Webhook"
3. Configure event filters (which events trigger the notification)
4. Set the webhook URL and message template
5. Test with a sample event

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Webhook not firing | No matching destination filter | Check event name matches filter exactly |
| Duplicate webhooks | Event matches multiple destinations | Narrow destination filters |
| Webhook timeout | Handler too slow | Acknowledge with 200 immediately, process async |
| HogQL query timeout | Unfiltered table scan | Add `timestamp >` filter and `LIMIT` |
| 429 on events API | Too many queries | Cache results, reduce polling frequency |

## Output

- Webhook destination configured for specific events
- Express/Next.js webhook handler with event routing
- Event queries via REST API and HogQL
- Slack/CRM integration on user lifecycle events

## Examples

For a webhook destination, define the filtered event set, minimal payload, receiver authentication, idempotency key, retry behavior, and response logging; then use the built-in test flow before enabling it. For queries, use the regional private API with a scoped credential and a bounded time range.

## Resources

See [official PostHog references](references/official-docs.md) for current authority and verification boundaries.

- [PostHog CDP Destinations](https://posthog.com/docs/cdp/destinations)
- [PostHog Webhook Destination](https://posthog.com/docs/cdp/destinations/webhook)
- [PostHog Events API](https://posthog.com/docs/api/events)
- [HogQL Documentation](https://posthog.com/docs/sql)

## Next Steps

For deployment setup, see `posthog-deploy-integration`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
windsurf-webhooks-events The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output. CX Codex +1 1installs twinmind-webhooks-events twinmind-webhooks-events — a skill for TwinMind meeting events: transcription completion, action item extraction, and calendar sync notifications. CX Codex +1 1installs firecrawl-webhooks-events firecrawl-webhooks-events sets up Firecrawl webhook ingestion with raw HMAC-SHA256 signature verification, deduplication, and polling fallback. CX Codex +1 1installs coderabbit-webhooks-events coderabbit-webhooks-events is a Claude Code skill for designing Git-provider event automation around CodeRabbit reviews. It checks signatures and tests replay handling. CX Codex +1 1installs instantly-webhooks-events instantly-webhooks-events guides the setup and operation of Instantly API v2 webhooks with schema checks, deduplication, and privacy safeguards. CX Codex +1 1installs windsurf-data-handling The windsurf-data-handling skill maps data flows, sets context exclusions, and gathers evidence for privacy and compliance reviews around Devin Desktop, formerly Windsurf. CX Codex +1 1installs windsurf-flows-automation windsurf-flows-automation — a skill for building and managing Windsurf Flows, the automation scripts for repetitive dev work. Turn routine tasks into one-command flows. CX Codex +1 1installs lindy-core-workflow-b lindy-core-workflow-b is a Claude Code skill for configuring Lindy triggers, Cron schedules, and multi-agent delegation. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open