PostHog integration

What it does

The PostHog integration lets your agency run product-analytics operations on behalf of your clients without leaving TaskJuice. Connect a client's PostHog project once and you can capture events into their pipeline, list events for reporting, update person properties, list feature flags, create static or dynamic cohorts, and list saved insights. A webhook trigger fires whenever a PostHog action matches an incoming event, so you can chain product behavior into the rest of your workflow.

Connect a PostHog account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose PostHog and click Connect.
3. Pick the right host for the client's PostHog instance. Use https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud, or the base URL of a self-hosted PostHog install.
4. In PostHog, open Settings, Personal API keys, create a new key scoped to the project you want TaskJuice to manage, and paste the value into TaskJuice.
5. Copy the numeric Project ID from the PostHog project settings and the project's public Project API Key (begins with phc_) used for event ingestion, then paste both values into the connection form.

See the PostHog API authentication docs for the full key-scoping flow.

Triggers

• posthog/action-triggered fires when a PostHog action matches an incoming event. Configure a Webhook destination in PostHog under Data, Pipeline, Destinations, point it at the TaskJuice ingress URL for this trigger, and tie it to one or more actions.

PostHog signs every webhook with an HMAC-SHA256 hex digest of the raw body on the X-PostHog-Signature header. TaskJuice verifies the signature against the shared signing secret configured on the PostHog webhook destination before activating the workflow.

Actions

• posthog/capture-event tracks a product event in PostHog. Uses the project's write-only API token in the body, supports custom properties and an optional timestamp.
• posthog/list-events lists ingested events for the project, with optional event-name, after, and before filters. Paginated via cursor URLs.
• posthog/update-person merges properties onto a PostHog person record by numeric ID.
• posthog/list-feature-flags lists feature flags configured for the project, with optional active filter and cursor pagination.
• posthog/create-cohort creates a static or dynamic cohort. Supply name, description, and PostHog filter groups.
• posthog/list-insights lists saved insights (trends, funnels, paths, retention) for the project.

Known limitations

• PostHog's REST API enforces a per-key, per-endpoint rate limit. When the budget is exhausted PostHog returns a 429 status, which TaskJuice surfaces as a retryable error so downstream resilience policies can back off.
• Personal API keys are scoped per project. A connection with a key scoped to the wrong project will fail with a 403 on every admin-API call. Recreate the key with the right project scope and reconnect.
• The /capture/ ingestion endpoint accepts the project's public write-only token in the request body and does not use Bearer auth. The personal API key only authenticates the admin endpoints (events, persons, feature flags, cohorts, insights).
• Self-hosted PostHog instances must be reachable from TaskJuice's network. Behind-VPN or local-only deployments are not supported.
• Pagination uses next URLs returned in each response. Workflows that need every page should drive paging explicitly off the next field.