PostHog Webhooks & Events

Overview

Handle PostHog webhooks triggered by Actions and event-based alerts. PostHog fires webhooks when defined Actions match incoming events, allowing you to send notifications, update external systems, or trigger workflows based on user behavior patterns.

Prerequisites

• PostHog project with API access (cloud or self-hosted)

• PostHog project API key and personal API key

• HTTPS endpoint for receiving webhook deliveries

• Actions configured in PostHog dashboard

Webhook Event Types

Event Source Trigger Payload

Action webhook Action matches event Event properties, person data

Zapier integration Action fires Structured action data

HogQL alert Query threshold exceeded Alert details, query results

Feature flag change Flag toggled Flag key, rollout percentage

Export completed Data export finishes Export URL, row count

Instructions

Step 1: Create an Action with Webhook

Use the PostHog API to create an Action that fires on specific events (e.g., autocapture on signup page). Configure the Action's steps with event type and URL matching.

Step 2: Configure Webhook Endpoint

Build an Express endpoint at /webhooks/posthog that receives the event payload (event name, person data, properties, timestamp). Acknowledge with 200 immediately, then route to handlers.

Step 3: Route and Handle Events

Implement a switch on event name to dispatch to specific handlers: onUserSignup (sync to CRM, Slack notify), onSubscriptionUpgrade (revenue tracking), onFeatureActivated (adoption tracking).

Step 4: Query Events via API

Use the PostHog events API to query recent events by name and time range for reporting and analysis.

For complete TypeScript implementations, event handlers, and API query code, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Error Handling

Issue Cause Solution

Webhook not firing Action not matched Test Action with debug mode in PostHog

Missing person data Anonymous user Ensure posthog.identify() called first

Duplicate events Action matches multiple Refine Action event/URL filters

Rate limited Too many API calls Use batch endpoints for queries

Resources

• PostHog Webhooks

• PostHog Actions

• PostHog API Reference

Next Steps

For deployment setup, see posthog-deploy-integration .

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See PostHog implementation details for output format specifications.

Examples

Basic usage: Apply posthog webhooks events to a standard project setup with default configuration options.

Advanced scenario: Customize posthog webhooks events for production environments with multiple constraints and team-specific requirements.