PostHog integration

What it does

The PostHog integration connects a client's PostHog project to your workflows. Two real-time triggers start a workflow when a user signs up, upgrades, hits a pricing page, or matches any PostHog action you define. Actions send events and person data into PostHog from other tools, look up and update persons, add them to cohorts, evaluate or toggle feature flags, annotate charts, and pull insight results or HogQL query rows into reports.

Typical uses are syncing sign-ups and upgrades into a CRM, alerting a sales channel when an account hits a usage milestone, capturing server-side events from billing or support tools, and posting a weekly KPI snapshot to a client's Slack.

Connect a PostHog account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose PostHog and click Connect.
3. Enter the PostHog Cloud region: us if the project lives at us.posthog.com, eu if it lives at eu.posthog.com. TaskJuice sends event capture and flag evaluation to the region's ingestion host and everything else to its app host, as PostHog requires.
4. In PostHog, open Settings, Personal API keys, and create a key limited to the client's project. Give it the read scopes person:read, insight:read, cohort:read, feature_flag:read, action:read, event_definition:read and query:read, and the write scopes person:write, cohort:write, feature_flag:write, annotation:write and hog_function:write. The hog_function:write scope is what lets TaskJuice create the webhook destinations the triggers need. Paste the key into TaskJuice.
5. From Project settings, copy the numeric Project ID and the Project API key (it begins with phc_) and paste both into the connection form. The project key is the write-only token PostHog uses for event capture.

See PostHog's personal API key docs for how to create and scope a key.

Triggers

• posthog/event-captured (New Event) fires each time PostHog ingests an event with the name you pick, such as $pageview or a custom event like order_completed.
• posthog/action-triggered (Action Performed) fires each time an event matches the PostHog action you pick. Use an action when the condition is more than an event name, for example a pageview on /pricing or a click on a specific button.

Both triggers are set up for you. When you publish the workflow, TaskJuice creates an HTTP Webhook destination in the client's PostHog project, filtered to the event or action you chose, and removes it again when you unpublish. You do not need to build the destination by hand. Each delivery carries the PostHog event (name, distinct ID, timestamp, properties), the person with their properties, any groups, and the project. Use person.id with Update Person, Delete Person, or the cohort actions.

PostHog does not sign webhook deliveries. TaskJuice sets a random secret as an Authorization header on the destination it creates and rejects any delivery that does not carry it.

Actions

Event capture (uses the project API key):

• posthog/capture-event sends a custom event for a person, with properties and an optional timestamp.
• posthog/identify-person creates or updates a person by distinct ID with set and set-once properties.
• posthog/identify-group creates or updates a group, such as a company, with properties for group analytics.
• posthog/create-alias links a second distinct ID to an existing person so events under both IDs merge.
• posthog/track-page records a $pageview with the page URL, title, and referrer.
• posthog/track-screen records a $screen view for mobile apps.
• posthog/evaluate-feature-flags returns every flag's enabled state and variant for one person (and their groups, for group-based flags), so a workflow can branch on a rollout or experiment.

Persons and cohorts:

• posthog/find-person looks up persons by distinct ID, email, or a search term.
• posthog/update-person sets properties on a person by UUID.
• posthog/delete-person permanently deletes the person behind a distinct ID, optionally with their events and session recordings, for example to honor an erasure request.
• posthog/create-cohort creates a static or dynamic cohort.
• posthog/add-person-to-cohort and posthog/remove-person-from-cohort manage membership of a static cohort.

Feature flags:

• posthog/list-feature-flags lists the project's flags.
• posthog/update-feature-flag turns a flag on or off.

Analytics and reporting:

• posthog/list-events lists recent events with name and date filters. PostHog has deprecated this endpoint, so prefer Run HogQL Query in new workflows.
• posthog/run-hogql-query runs a HogQL (SQL) query and returns the rows.
• posthog/list-insights lists saved insights.
• posthog/get-insight fetches an insight with its latest result, optionally recalculated.
• posthog/create-annotation marks a release, campaign, or incident on the client's charts.

Known limitations

• The integration supports PostHog Cloud (US and EU). Self-hosted PostHog is not supported.
• Each published trigger is one webhook destination in PostHog. Destination deliveries count toward the client's PostHog data pipelines usage, which includes a monthly free allowance.
• The secret header is stored in the destination's configuration, so anyone with access to the client's PostHog project settings can read it. Republish the workflow to rotate it.
• Track Page View sends the URL, title, and referrer only. To attach other properties, use Capture Event with the event name $pageview.
• PostHog applies person updates and deletions asynchronously, so a Find Person straight after an update can still return the old values for a few seconds.
• PostHog rate-limits personal API keys across the whole organization: 240 requests a minute for analytics endpoints such as insights and persons, 480 a minute for other reads and writes, and 2,400 an hour for HogQL queries. A 429 is surfaced as a retryable error. Event capture and flag evaluation are not rate limited.
• Event capture answers success even when PostHog drops the event later, for example when the distinct ID is empty or the project is over its billing quota. Check the event in PostHog when testing a new workflow.
• Run HogQL Query returns up to 100 rows unless the query sets its own LIMIT (up to 50,000). PostHog does not support the query endpoint for bulk or recurring exports.