fix(posthog): validate integration against live API docs, add self-hosted support + CRUD coverage (#5476)

* fix(posthog): validate integration against live API docs, add self-hosted support + CRUD coverage

Fix missing response.ok checks across ~36 tools that silently treated
error bodies as success. Fix delete_feature_flag ignoring failure
responses, evaluate_flags targeting the undocumented /decide endpoint
without the required api_key body field, and batch_events reporting a
hardcoded events_processed count.

Add self-hosted host support (utils.ts) alongside the existing US/EU
region selector, and complete CRUD coverage with 5 new tools:
update_insight, update_cohort, update_experiment, delete_survey,
create_dashboard.

* fix(posthog): remove dead response.ok checks, fix real schema/endpoint bugs

The prior commit added if (!response.ok) branches inside transformResponse
across ~40 tool files. This is dead code — tools/index.ts already throws
on non-2xx (and error-payload) responses before transformResponse is ever
invoked, so transformResponse only ever receives already-successful
responses. Reverted to the idiomatic no-error-branch pattern used
elsewhere in the codebase (e.g. hunter/email_verifier.ts), and added a
posthog-errors errorExtractor so the framework's own error throw surfaces
PostHog's real {type, code, detail, attr} error shape instead of a
generic status message.

Verified against PostHog's live OpenAPI schema, fixed real bugs:
- delete_feature_flag: DELETE always returns 405 (hard delete not
  allowed); switched to PATCH with deleted: true
- delete_person: no single-person DELETE endpoint exists; switched to
  POST .../persons/bulk_delete/ with ids: [personId]
- create_annotation: insight_short_id is read-only on create; the
  writable field is dashboard_id
- removed nonexistent fields (experiment variants, insight
  filters/saved) not present in the current schema
- added missing trailing slashes on feature-flag/experiment URLs

* fix(posthog): reject unsafe self-hosted host values (SSRF)

The self-hosted host field accepted any string and only stripped
trailing slashes before prepending https://, so a workflow could point
it at loopback/private/link-local addresses (e.g. cloud instance-
metadata endpoints) and the executor would make a real server-side
request to it. Reuse the shared validateExternalUrl SSRF guard, same
pattern already used for Convex's custom deployment URL
(tools/convex/utils.ts); the tool executor separately re-validates with
DNS resolution and pins the resolved IP for the actual request.

Also drop an unused params arg in evaluate_flags' headers function.

* fix(posthog): fail loudly instead of silently dropping data on bad JSON params

Several tools caught JSON.parse failures on user-supplied filter/query/
parameters strings and silently substituted {} or null, which would
wipe the corresponding field on the PATCH/create request instead of
surfacing an error (Cursor Bugbot flagged this for update_cohort,
update_experiment, update_insight; the same pattern existed in their
create_* / update_feature_flag / evaluate_flags counterparts, fixed for
consistency). Now throws a descriptive error, matching the existing
convention in tools/notion/query_database.ts.

Also fixes batch_events: the request body silently sent an empty batch
on invalid JSON, and transformResponse always reported "captured
successfully" even when PostHog's response indicated failure
(data.status !== 1).

* fix(posthog): mark region required for update_experiment

posthog_update_experiment was the only experiment operation missing
from the region field's required-condition list; the other three
(create/get/list) already require it. Region is unconditionally
visible on this block (no condition key gates it), so this was a
required-ness inconsistency rather than a functional bug, but users
updating an EU experiment should still be prompted to select the
region explicitly rather than relying on the default.

* fix(posthog): fix cross-field value leakage and false-success reports

Merges update_insight's query subblock into the same insightQuery id
already used by create_insight (Cursor flagged: it previously reused
the 'query' subblock id shared by posthog_query's HogQL field and the
cohort query fields, so switching operations could carry a stale
HogQL/cohort-JSON value into an insight PATCH). Matches the existing
merged-condition pattern used elsewhere in this block instead of
duplicating the subblock id.

Also fixes two more false-success reports in the same class as the
batch_events/delete_feature_flag fixes: capture_event now checks the
ingest response's status field (same {"status": 1} contract as
/batch/) instead of unconditionally returning success, and
delete_person now reports failure when persons_deleted is 0 instead of
always success: true.

Author: waleedlatif1

apps/sim/blocks/blocks/posthog.ts

@@ -243,6 +243,17 @@ const ERROR_EXTRACTORS: ErrorExtractorConfig[] = [
       return undefined
     },
   },
+  {
+    id: 'posthog-errors',
+    description: 'PostHog API error format with type/code/detail/attr fields',
+    examples: ['PostHog API'],
+    extract: (errorInfo) => {
+      const detail = errorInfo?.data?.detail
+      if (typeof detail !== 'string' || !detail.trim()) return undefined
+      const attr = errorInfo?.data?.attr
+      return typeof attr === 'string' && attr ? `${detail} (${attr})` : detail
+    },
+  },
   {
     id: 'plain-text-data',
     description: 'Plain text error response',
@@ -320,6 +331,7 @@ export const ErrorExtractorId = {
   SOAP_FAULT: 'soap-fault',
   OAUTH_ERROR_DESCRIPTION: 'oauth-error-description',
   NESTED_ERROR_OBJECT: 'nested-error-object',
+  POSTHOG_ERRORS: 'posthog-errors',
   PLAIN_TEXT_DATA: 'plain-text-data',
   HTTP_STATUS_TEXT: 'http-status-text',
 } as const

apps/sim/tools/error-extractors.ts

@@ -1,8 +1,11 @@
+import { getErrorMessage } from '@sim/utils/errors'
+import { getPostHogIngestBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export interface PostHogBatchEventsParams {
   projectApiKey: string
   region?: 'us' | 'eu'
+  host?: string
   batch: string
 }
 
@@ -35,6 +38,13 @@ export const batchEventsTool: ToolConfig<PostHogBatchEventsParams, PostHogBatchE
       description: 'PostHog region: us (default) or eu',
       default: 'us',
     },
+    host: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description:
+        'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+    },
     batch: {
       type: 'string',
       required: true,
@@ -46,49 +56,44 @@ export const batchEventsTool: ToolConfig<PostHogBatchEventsParams, PostHogBatchE
 
   request: {
     url: (params) => {
-      const baseUrl =
-        params.region === 'eu' ? 'https://eu.i.posthog.com' : 'https://us.i.posthog.com'
+      const baseUrl = getPostHogIngestBaseUrl(params.region, params.host)
       return `${baseUrl}/batch/`
     },
     method: 'POST',
     headers: (params) => ({
       'Content-Type': 'application/json',
     }),
     body: (params) => {
-      let batch: any[]
+      let batch: unknown
       try {
         batch = JSON.parse(params.batch)
-      } catch (e) {
-        batch = []
+      } catch (error) {
+        throw new Error(`Invalid batch JSON: ${getErrorMessage(error)}`)
+      }
+      if (!Array.isArray(batch)) {
+        throw new Error('batch must be a JSON array of events')
       }
 
       return {
         api_key: params.projectApiKey,
-        batch: batch,
+        batch,
       }
     },
   },
 
-  transformResponse: async (response: Response) => {
-    if (response.ok) {
-      const data = await response.json()
-      return {
-        success: true,
-        output: {
-          status: 'Batch events captured successfully',
-          events_processed: data.status === 1 ? JSON.parse(data.batch || '[]').length : 0,
-        },
-      }
-    }
+  transformResponse: async (response: Response, params) => {
+    const data = await response.json()
+    const eventsProcessed = params ? (JSON.parse(params.batch) as unknown[]).length : 0
+    const success = data.status === 1
 
-    const error = await response.text()
     return {
-      success: false,
+      success,
       output: {
-        status: 'Failed to capture batch events',
-        events_processed: 0,
+        status: success
+          ? 'Batch events captured successfully'
+          : `Batch events capture failed (status: ${data.status})`,
+        events_processed: success ? eventsProcessed : 0,
       },
-      error: error || 'Unknown error occurred',
     }
   },
 

apps/sim/tools/posthog/batch_events.ts

@@ -1,8 +1,11 @@
+import { getErrorMessage } from '@sim/utils/errors'
+import { getPostHogIngestBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export interface PostHogCaptureEventParams {
   projectApiKey: string
   region?: 'us' | 'eu'
+  host?: string
   event: string
   distinctId: string
   properties?: string
@@ -38,6 +41,13 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
         description: 'PostHog region: us (default) or eu',
         default: 'us',
       },
+      host: {
+        type: 'string',
+        required: false,
+        visibility: 'user-only',
+        description:
+          'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+      },
       event: {
         type: 'string',
         required: true,
@@ -69,8 +79,7 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
 
     request: {
       url: (params) => {
-        const baseUrl =
-          params.region === 'eu' ? 'https://eu.i.posthog.com' : 'https://us.i.posthog.com'
+        const baseUrl = getPostHogIngestBaseUrl(params.region, params.host)
         return `${baseUrl}/capture/`
       },
       method: 'POST',
@@ -87,8 +96,8 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
         if (params.properties) {
           try {
             body.properties = JSON.parse(params.properties)
-          } catch (e) {
-            body.properties = {}
+          } catch (error) {
+            throw new Error(`Invalid properties JSON: ${getErrorMessage(error)}`)
           }
         }
 
@@ -101,22 +110,16 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
     },
 
     transformResponse: async (response: Response) => {
-      if (response.ok) {
-        return {
-          success: true,
-          output: {
-            status: 'Event captured successfully',
-          },
-        }
-      }
+      const data = await response.json()
+      const success = data.status === 1
 
-      const error = await response.text()
       return {
-        success: false,
+        success,
         output: {
-          status: 'Failed to capture event',
+          status: success
+            ? 'Event captured successfully'
+            : `Event capture failed (status: ${data.status})`,
         },
-        error: error || 'Unknown error occurred',
       }
     },
 

apps/sim/tools/posthog/capture_event.ts

@@ -1,14 +1,16 @@
+import { getPostHogAppBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 interface PostHogCreateAnnotationParams {
   apiKey: string
   projectId: string
   region: string
+  host?: string
   content: string
   date_marker: string
   scope?: string
   dashboard_item?: string
-  insight_short_id?: string
+  dashboard_id?: string
 }
 
 interface PostHogCreateAnnotationResponse {
@@ -21,6 +23,7 @@ interface PostHogCreateAnnotationResponse {
     updated_at: string
     created_by: Record<string, any> | null
     dashboard_item: number | null
+    dashboard_id: number | null
     insight_short_id: string | null
     insight_name: string | null
     scope: string
@@ -37,6 +40,7 @@ export const createAnnotationTool: ToolConfig<
   description:
     'Create a new annotation in PostHog. Mark important events on your graphs with date and description.',
   version: '1.0.0',
+  errorExtractor: 'posthog-errors',
 
   params: {
     apiKey: {
@@ -58,6 +62,13 @@ export const createAnnotationTool: ToolConfig<
       description: 'PostHog cloud region: "us" or "eu" (default: "us")',
       default: 'us',
     },
+    host: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description:
+        'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+    },
     content: {
       type: 'string',
       required: true,
@@ -75,25 +86,28 @@ export const createAnnotationTool: ToolConfig<
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Scope of the annotation: "project" or "dashboard_item" (default: "project")',
+      description:
+        'Scope of the annotation: "project", "organization", "dashboard", or "dashboard_item" (default: "project")',
     },
     dashboard_item: {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'ID of dashboard item to attach this annotation to',
+      description:
+        'ID of the dashboard tile (insight) to attach this annotation to (used when scope is "dashboard_item")',
     },
-    insight_short_id: {
+    dashboard_id: {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Short ID of the insight to attach this annotation to',
+      description:
+        'ID of the dashboard to attach this annotation to (used when scope is "dashboard")',
     },
   },
 
   request: {
     url: (params) => {
-      const baseUrl = params.region === 'eu' ? 'https://eu.posthog.com' : 'https://us.posthog.com'
+      const baseUrl = getPostHogAppBaseUrl(params.region as 'us' | 'eu' | undefined, params.host)
       return `${baseUrl}/api/projects/${params.projectId}/annotations/`
     },
     method: 'POST',
@@ -115,8 +129,8 @@ export const createAnnotationTool: ToolConfig<
         body.dashboard_item = Number(params.dashboard_item)
       }
 
-      if (params.insight_short_id) {
-        body.insight_short_id = params.insight_short_id
+      if (params.dashboard_id) {
+        body.dashboard_id = Number(params.dashboard_id)
       }
 
       return body
@@ -136,6 +150,7 @@ export const createAnnotationTool: ToolConfig<
         updated_at: data.updated_at,
         created_by: data.created_by || null,
         dashboard_item: data.dashboard_item || null,
+        dashboard_id: data.dashboard_id || null,
         insight_short_id: data.insight_short_id || null,
         insight_name: data.insight_name || null,
         scope: data.scope || '',
@@ -175,6 +190,11 @@ export const createAnnotationTool: ToolConfig<
       description: 'ID of dashboard item this annotation is attached to',
       optional: true,
     },
+    dashboard_id: {
+      type: 'number',
+      description: 'ID of the dashboard this annotation is attached to',
+      optional: true,
+    },
     insight_short_id: {
       type: 'string',
       description: 'Short ID of the insight this annotation is attached to',
@@ -187,7 +207,7 @@ export const createAnnotationTool: ToolConfig<
     },
     scope: {
       type: 'string',
-      description: 'Scope of the annotation (project or dashboard_item)',
+      description: 'Scope of the annotation (project, organization, dashboard, or dashboard_item)',
     },
     deleted: {
       type: 'boolean',

apps/sim/tools/posthog/create_annotation.ts

@@ -1,9 +1,11 @@
+import { getPostHogAppBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 interface PostHogCreateCohortParams {
   apiKey: string
   projectId: string
   region: string
+  host?: string
   name: string
   description?: string
   filters?: string
@@ -38,6 +40,7 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
     description:
       'Create a new cohort in PostHog. Requires cohort name and filter or query configuration.',
     version: '1.0.0',
+    errorExtractor: 'posthog-errors',
 
     params: {
       apiKey: {
@@ -59,6 +62,13 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
         description: 'PostHog cloud region: "us" or "eu" (default: "us")',
         default: 'us',
       },
+      host: {
+        type: 'string',
+        required: false,
+        visibility: 'user-only',
+        description:
+          'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+      },
       name: {
         type: 'string',
         required: false,
@@ -101,7 +111,7 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
 
     request: {
       url: (params) => {
-        const baseUrl = params.region === 'eu' ? 'https://eu.posthog.com' : 'https://us.posthog.com'
+        const baseUrl = getPostHogAppBaseUrl(params.region as 'us' | 'eu' | undefined, params.host)
         return `${baseUrl}/api/projects/${params.projectId}/cohorts/`
       },
       method: 'POST',