Skip to main content

PostHog Webhook Integration

The PostHog Webhook Integration allows you to seamlessly ingest product analytics events from your PostHog project directly into your OpenCDP workspace. By configuring a webhook in PostHog, OpenCDP can automatically sync user identities, device registrations, and custom tracking events in real time.

Overview​

The integration exposes a dedicated data gateway endpoint: POST /data-gateway/v1/posthog

This endpoint processes incoming webhook payloads from PostHog and maps them to OpenCDP's internal data structures:

  • $identify events: Creates or updates user profiles in OpenCDP.
  • $register_device events: Registers user devices (e.g., for push notifications).
  • Custom track events: Records user activities and behaviors, preserving PostHog-specific metadata.

Prerequisites​

Before setting up the integration, ensure you have:

  1. An active OpenCDP Workspace.
  2. A valid OpenCDP API Key (used to authenticate requests from PostHog).
  3. A PostHog Project with access to configure Data Pipelines or Webhook destinations.

Endpoint & Authentication​

  • Webhook URL: https://api.opencdp.io/gateway/data-gateway/v1/posthog
  • Method: POST
  • Authentication: You must provide your OpenCDP API Key in the Authorization HTTP header.

Required Header​

Authorization: <YOUR_OPEN_CDP_API_KEY>

Payload Requirements​

The OpenCDP webhook expects the standard JSON payload format generated by PostHog. At a minimum, the payload must contain an event object.

{
  "event": {
    "event": "event_name",
    "properties": { ... },
    "distinct_id": "user_123",
    "uuid": "...",
    "timestamp": "2023-10-01T12:00:00Z"
  }
}

Event Mapping Behavior​

1. Identifying Users ($identify)​

When PostHog sends an $identify event, OpenCDP captures the user's details and updates their profile.

  • Trigger: PostHog event named $identify.
  • Identifier: OpenCDP looks for the user's ID in event.properties.id first. If missing, it falls back to event.distinct_id.
  • Properties: All properties sent inside event.properties are attached to the identified user in OpenCDP.

2. Registering Devices ($register_device)​

To track mobile devices (e.g., for push campaigns), you can send a $register_device event from PostHog.

  • Trigger: PostHog event named $register_device.
  • Required Properties: The event properties must include:
    • device_id: A unique identifier for the device.
    • platform: The device platform (e.g., ios, android, web).
    • fcm_token: The Firebase Cloud Messaging token for push notifications.
  • Optional Properties: You can also include name, os_version, model, apn_token, app_version, last_active_at, and an attributes object containing further device metadata.

Example Device Registration Payload:

{
  "event": {
    "event": "$register_device",
    "distinct_id": "user_123",
    "properties": {
      "device_id": "device_abc_123",
      "platform": "ios",
      "fcm_token": "fcm_xyz_987",
      "os_version": "17.0",
      "app_version": "1.2.0"
    }
  }
}

3. Custom Tracking Events​

All other events that are not $identify or $register_device are processed as standard Track events.

  • Trigger: Any event name other than the predefined ones.
  • Loop Prevention: Events where the identifier contains the word "posthog" (case-insensitive) are ignored to prevent recursive loops or handling internal PostHog system users.
  • Metadata Context: OpenCDP automatically captures the event properties and nests PostHog-specific metadata (uuid, distinct_id, url, timestamp) inside a posthog property within the Track event payload.

Setup Instructions in PostHog​

To start sending data from PostHog to OpenCDP:

  1. Log in to your PostHog dashboard.
  2. Navigate to Data Pipeline > Destinations (or Webhooks).
  3. Create a new Destination and choose the Webhook option.
  4. Set the Webhook URL to your OpenCDP endpoint: https://api.opencdp.io/gateway/data-gateway/v1/posthog
  5. In the headers configuration section, add a new header:
    • Key: Authorization
    • Value: <YOUR_OPEN_CDP_API_KEY>
  6. Configure the destination to trigger on all events, or filter for specific events like $identify and $register_device.
  7. Save and enable the webhook.

Troubleshooting​

  • 401 Unauthorized: Ensure your OpenCDP API key is valid, unexpired, and correctly placed in the Authorization header.
  • 400 Bad Request / Validation Error: Verify that your PostHog payload contains the event root object and an identifier (distinct_id or id). If registering a device, ensure all required properties (device_id, platform, fcm_token) are present.
  • Events Not Appearing: Check if the identifier in PostHog contains the word "posthog". OpenCDP deliberately ignores identifiers containing "posthog" to prevent infinite loops.