PostHog

1. Overview

PostHog is an open-source product analytics platform that helps you understand user behavior, track events, and conduct A/B testing. It provides a comprehensive suite of tools for session recording, feature flags, and automated insights, all of which can be self-hosted for complete data control.

The GoInsight Posthog node allows you to integrate event tracking and user management directly into your automated workflows. You can send crucial data to your PostHog instance without writing any code, enabling you to capture key user interactions from various sources. Key capabilities include:

• Event Tracking: Create custom events to monitor user actions, such as sign-ups, purchases, or feature usage.
• User Identification: Identify users and update their properties to build a complete profile of their attributes and behavior.
• Alias Management: Link multiple user identities (e.g., an anonymous ID and an email) to a single user profile.
• Page and Screen Tracking: Log page views and screen views to analyze user navigation patterns in web and mobile applications.

2. Prerequisites

Before using this node, you must have a valid Posthog account, whether on PostHog Cloud or a self-hosted instance. You will need your Project API Key and your instance URL to configure the credentials in GoInsight.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following core resources within PostHog: Alias, Event, Identity, Page, and Screen.

Operation Details

Create an Alias

Merge two user identities in PostHog by creating an alias. Links anonymous users to authenticated identity (e.g., anonymous_123 → user@example.com).

Use Case: Connect pre-login browsing with post-login profile.

Output: Returns {"status": 1} on success. StatusCode: 200=Success, 429=Rate limited, 500=Error.

Input Parameters:

• DistinctId: The current unique identifier (anonymous ID or user ID) of the user. Can be a session ID, cookie ID, or any anonymous identifier. Example: 'user_12345', 'anonymous_c7c9b2f4', or 'session_xyz789'.
• Alias: The new alias (foreign ID) to associate with the Distinct ID. Typically the authenticated user's email or database ID. Used for user identification and merging. Example: 'john.doe@example.com', 'authenticated_user_456', or 'db_user_789'.

Output:

• Data (object): The raw response data from PostHog API. Structure varies by status: On success (200): typically {"status": 1}. On error or non-JSON response: {"raw_content": "response_text"}. On 429 rate limit: may be empty {}. This field provides the server's actual response for debugging and data extraction.
• OriginalStatusCode (number): The original HTTP status code from PostHog API. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 429=Rate limited (retry later), 500=System error. Use this to determine if the operation succeeded.
• ErrorMessage (string): Human-readable error description. Empty string ("") if operation succeeded (StatusCode 200). Contains error details for any failure scenario (parameter error, rate limit, server error, or network exception). Use this for logging and user feedback.

Create an Event

Track user behavior with custom events in PostHog. Records actions like button clicks, purchases, or feature usage.

Use Case: Analyze product usage and engagement patterns.

Timestamp: Auto-generated; add manually for historical imports.

Output: StatusCode: 200=Success, 429=Rate limited, 500=Error.

Input Parameters:

• EventName: The name of the custom event to track (e.g., 'user_signed_up', 'purchase_completed', 'feature_viewed'). Use snake_case format for consistency.
• DistinctId: Unique user identifier for tracking (e.g., 'user_123', 'john@example.com', or 'session_abc123'). This identifies who triggered the event.

Options:

• Properties: Additional event properties as key-value pairs to add context to the event. Standard Properties: timestamp (number): Unix timestamp in milliseconds (e.g., 1704096000000). If not provided, automatically uses current server time. Use for importing historical events. Custom Properties: Add any custom data relevant to your event. Examples: Real-time event: {"amount": 99.99, "currency": "USD", "plan": "premium"}. Historical event: {"timestamp": 1704096000000, "amount": 99.99, "currency": "USD"}. Note: All values should be strings, numbers, booleans, or null.

Output:

• Data (object): The raw response data from PostHog Capture API. On success (StatusCode 200): typically {"status": 1}. This confirms the event was accepted.
• OriginalStatusCode (number): The original HTTP status code from PostHog API. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 429=Rate limited (retry later), 500=System error (timeout/connection). Use this to determine if the operation succeeded.
• ErrorMessage (string): Human-readable error description. Empty string if operation succeeded. Contains details for failures (parameter error, timeout, rate limit, API error).

Create an Identity

Identify users and update properties in PostHog using the $identify event. Links distinct IDs with user attributes (name, email, plan).

Use Case: Sync CRM data, update profiles on signup/login.

Properties: $set for updates, $set_once for immutable fields.

Output: StatusCode: 200=Success, 429=Rate limited, 500=Error.

Input Parameters:

• DistinctId: The unique identifier for the user in your database. Can be email, UUID, user ID, or any identifier. Examples: 'user_12345', 'john.doe@example.com', '550e8400-e29b-41d4-a716-446655440000'.

Options:

• Name: User's full name. This is a commonly used property that will be set via $set (overwritable). Example: 'John Doe'.
• Email: User's email address. This is a commonly used property that will be set via $set (overwritable). Example: 'john@example.com', 'zhangsan@company.com'.
• Plan: User's current subscription plan. This is a commonly used property that will be set via $set (overwritable). Example: 'free', 'premium', 'enterprise', 'trial'.
• SignupDate: The date when the user first signed up. This is a commonly used property that will be set via $set_once (set only if not exists). Example: '2024-02-03', '2024-01-15'.
• ReferralSource: The source from which the user was referred. This is a commonly used property that will be set via $set_once (set only if not exists). Example: 'google', 'facebook', 'twitter', 'direct', 'friend_referral'.
• PropertiesSet: Additional custom properties to set via $set (overwrite existing values). Use this for any other attributes beyond the common fields above. Example: {"company": "Acme Inc", "phone": "+1-555-0100", "job_title": "Product Manager"}. Common additional properties: company, phone, department, timezone, language, theme.
• PropertiesSetOnce: Additional custom properties to set via $set_once (set only if they don't already exist). Use this for any other immutable attributes beyond the common fields above. Example: {"initial_utm_source": "google", "account_creation_method": "email", "signup_country": "US"}. Common additional properties: initial_utm_campaign, first_purchase_date, initial_device_type.

Output:

• Data (object): The API response data from PostHog. On success (StatusCode 200): typically {"status": 1}. On error: may contain error details or be empty {}. This represents the server's acknowledgment of the identify event.
• OriginalStatusCode (number): The original HTTP status code from PostHog API. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code. Success: 200. Parameter error: -1. Timeout: 500. Other HTTP errors: original status code.
• ErrorMessage (string): Human-readable error description. Empty string if operation succeeded. Contains details for any failure (parameter error, timeout, API error, etc.).

Track a Page

Track page views to analyze user navigation in PostHog. Captures visited pages with URLs, referrers, and marketing attribution.

Use Case: Monitor landing pages, track journeys, measure campaigns.

Auto-tracking: Captures timestamp; override for historical data.

Output: StatusCode: 200=Success, 429=Rate limited, 500=Error.

Input Parameters:

• DistinctId: Unique user identifier for tracking (e.g., user ID, email, or session ID). Examples: 'user_12345', 'john@example.com', or 'session_abc123'.
• PageUrl: The full URL of the page being tracked (required). Must include protocol. Examples: 'https://mysite.com/home', 'https://mysite.com/products/123', or 'https://app.example.com/dashboard'.

Options:

• PageName: Optional human-readable name for the page (used for display in PostHog). Examples: 'Home Page', 'Product Details', 'User Dashboard'. If not provided, PostHog will use the URL pathname.
• Referrer: The referrer URL indicating where the user came from. This is a commonly used property for tracking traffic sources. Examples: 'https://google.com', 'https://facebook.com', 'https://twitter.com/post/123'. Leave empty for direct visits.
• Properties: Additional event properties as key-value pairs to add context to the page view. Common Properties: utm_source, utm_medium, utm_campaign: Marketing attribution. page_category, page_type: Page classification. timestamp (number): Unix timestamp in milliseconds. If not provided, automatically uses current server time. Examples: Real-time tracking: {"utm_source": "email", "utm_medium": "newsletter", "page_category": "product"}. Historical tracking: {"timestamp": 1704096000000, "page_category": "checkout"}. Note: All values should be strings, numbers, booleans, or null. The referrer can be set via the Referrer parameter or here.

Output:

• Data (object): The API response data from PostHog Capture API. On success (StatusCode 200): typically {"status": 1}. This confirms the page view event was accepted. On error: may contain error details or be empty {}.
• OriginalStatusCode (number): The original HTTP status code from PostHog API. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code. Success: 200. Parameter error: -1. Rate limited: 429. Server error: 500. Timeout: 504. Other HTTP errors: original status code.
• ErrorMessage (string): Human-readable error description. Empty string if operation succeeded. Contains details for failures (parameter error, timeout, rate limit, API error).

Track a Screen

Track screen views in mobile apps to analyze navigation in PostHog. Captures screens with device and app metadata.

Use Case: Monitor app flows, track feature usage in iOS/Android.

Auto-tracking: Captures timestamp; override for historical data.

Output: StatusCode: 200=Success, 429=Rate limited, 500=Error.

Input Parameters:

• DistinctId: Unique user identifier for tracking (e.g., 'user_123', 'john@example.com', or 'session_abc123'). This identifies who viewed the screen.
• ScreenViewName: The name of the screen viewed (e.g., 'Home Screen', 'Product Details Screen', 'User Profile Screen'). Used for display in PostHog analytics.

Options:

• ScreenCategory: Screen classification for grouping and analysis. This is a commonly used property for organizing screens by function. Examples: 'product', 'profile', 'settings', 'checkout', 'onboarding'. Leave empty if not applicable.
• AppVersion: Application version number. This is a commonly used property for tracking version-specific behavior and bugs. Examples: '2.1.0', '3.0.0-beta', '1.5.2'. Leave empty if unknown.
• DeviceType: Device type or platform. This is a commonly used property for device-specific analysis. Examples: 'iOS', 'Android', 'iPad', 'Android Tablet'. Leave empty if unknown.
• Properties: Additional event properties as key-value pairs to add context to the screen view. Common Properties: os_version: Operating system version (e.g., "14.5", "11.0"). device_model: Specific device model (e.g., "iPhone 12", "Pixel 5"). session_id: User session identifier. timestamp (number): Unix timestamp in milliseconds. If not provided, automatically uses current server time. Examples: Real-time tracking: {"os_version": "14.5", "device_model": "iPhone 12", "session_id": "abc123"}. Historical tracking: {"timestamp": 1704096000000, "os_version": "11.0"}. Note: All values should be strings, numbers, booleans, or null. The screen_category, app_version, and device_type can be set via independent parameters or here.

Output:

• Data (object): The API response data from PostHog Capture API. On success (StatusCode 200): typically {"status": 1}. This confirms the screen view event was accepted. On error: may contain error details or be empty {}.
• OriginalStatusCode (number): The original HTTP status code from PostHog API. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code. Success: 200. Parameter error: -1. Rate limited: 429. Network/server error: 500.
• ErrorMessage (string): Human-readable error description. Empty string if operation succeeded. Contains details for failures (parameter error, timeout, rate limit, API error).

5. Example Usage

This section will guide you through creating a simple workflow to track a "User Signed Up" event in PostHog whenever a new user is registered in your system.

The workflow will consist of a Start node, a Posthog: Create an Event node, and an Answer node.

1. Add the Posthog Node
   • In the workflow canvas, click the + button to add a new node.
   • Select the "Tools" tab in the pop-up panel.
   • Find and select "Posthog" from the list of tools.
   • From the list of supported operations for Posthog, click on "Create an Event" to add the node to your canvas.
2. Configure the Node
   • Click on the newly added "Create an Event" node to open its configuration panel on the right.
   • Credentials: In the "Credentials" field, select your pre-configured Posthog credential.
   • Parameters: Fill in the input parameters for the event.
   • DistinctId: This is the unique identifier for the user. You can map this from a previous node's output, for example, {{start.user_id}}. For this example, you can enter a test ID like user-12345.
   • EventName: Enter the name of the event you want to track. For this scenario, type User Signed Up.
   • Properties (Optional): This field accepts a JSON object for any additional data you want to associate with the event. For instance, you could track the user's subscription plan: {"plan": "premium", "source": "web_form"}.
3. Run and Validate
   • Once all required parameters are filled, any error indicators on the workflow should disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After the run completes successfully, you can click the logs icon to view the detailed input and output of the node. Check the StatusCode in the output; a value of 200 indicates that the event was successfully sent to PostHog.

After completing these steps, your workflow is fully configured. Every time it runs, it will send a "User Signed Up" event to your PostHog project, allowing you to analyze new user acquisition and behavior.

6. FAQs

Q: What is a DistinctId and why is it important?

A: The DistinctId is a unique identifier for a user in PostHog. It is crucial for correctly attributing events to users and building accurate user profiles. This ID should be consistent for a user across all their sessions and events. It could be a user ID from your database, an email address, or a randomly generated UUID.

Q: My events are not appearing in PostHog. What should I check?

A: If your events are not showing up, please verify the following:

• Credentials: Double-check that your Project API Key and PostHog Instance URL are correctly configured in your GoInsight credential.
• Node Output: Run the workflow and inspect the output of the Posthog node. Look for the StatusCode and ErrorMessage. A StatusCode other than 200 or a non-empty ErrorMessage will indicate a problem with the request.
• Data Ingestion Delay: There can sometimes be a slight delay before events appear in the PostHog UI. Please wait a few minutes and refresh.
• Ad Blockers: If you are testing on a browser, ensure that ad blockers or privacy extensions are not blocking requests to the PostHog API.

7. Official Documentation

For more in-depth information about the PostHog API and its features, please refer to the official documentation.

Posthog Official Documentation