Building workflows

A PostHog workflow is a directed graph: a list of action nodes (actions) wired by edges (edges), with exactly one trigger node that starts every run. You author that graph as JSON and ship it over MCP. Always call it a "workflow" to the user. "Hog flow" is the internal code name (HogFlow), not a user-facing term.

The single biggest failure mode is getting the graph JSON structurally wrong. The backend stores actions/config as loose JSON, but the visual editor parses every node against a strict schema, so a malformed node saves but then breaks the editor view for the whole workflow. Before composing or editing any graph, read references/graph-schema.md. It is the contract; do not improvise node shapes from these examples alone.

Before the first messaging workflow

When the user asks to set up workflows or messaging, or asks for an email, SMS or push workflow in a project that may not send yet, call workflows-setup-status before composing anything. It says which setup steps are open and links each one in the app. Walk the user through the open steps, set the sending rules, then offer suggested workflows. Read references/onboarding.md for the flow and the defaults to recommend.

Skip this for automations that only post to Slack or call webhooks: they need no email setup. If workflows-setup-status is not available, go straight to the lifecycle below.

The lifecycle

Work the workflow through these stages. Don't jump straight to enabling it.