Graph Schema

Contents

• Node (action) shape
• Action types and their config
• Edges
• function* inputs
• Duration strings (delay_duration, max_wait_duration)
• Waiting until a date (delay_until)
• Conversion & exit condition
• Pre-submit checklist

Node (action) shape

Every action object has these common fields plus a type-specific config:

• id — unique within the workflow; edges reference it by from/to.
• on_error — optional; only continue or abort. Omit to use the default.
• filters — optional property filters gating the action: {properties: [<cond>]}. Send properties, not bytecode.
• output_variable — optional; store a step result into a workflow variable. {key, result_path?, spread?}.

Action types and their config

Use only these type values — they are the complete supported set. An unknown or unsupported type breaks the editor’s parse for the entire graph.

Branch and wait condition filters (the filters wrapper is mandatory)

conditional_branch and wait_until_condition gate on a filters object, the action-filter shape ({properties?, events?, actions?, source?, filter_test_accounts?}). The wrapper is not optional:

• Write { "filters": { "properties": [<cond>] } } on each condition, never { "properties": [<cond>] } directly on the condition object. The bare form saves but the visual editor flags it and the branch compiles to a constant, so it never evaluates your condition.
• conditional_branch conditions are property-only (person/group <cond>s). Event/action filters are rejected here (“Event filters are not allowed in conditionals”).
• wait_until_condition is event-aware: its condition.filters and each events?[].filters may also carry events/actions. An entry naming neither an event nor an action is dropped (it would match everything).
• source is optional (defaults to events). Never send bytecode; the server compiles it from properties.

Trigger config (the trigger node)

Discriminated on config.type:

• event — { "type": "event", "filters": { "events": [{ "id": "<event>", "name": "<event>", "type": "events", "order": 0, "properties": [<cond>] }], "properties": [<cond>], "filter_test_accounts": false } }. Fires on every matching occurrence. Throttle repeats with trigger_masking (dedup/sampling — not behavioral filtering).
• webhook / manual / tracking_pixel — { "type": "webhook", "template_id": "<literal>", "inputs": { ... } }. These use a fixed built-in source template, not one you look up: template-source-webhook for both webhook and manual, template-source-webhook-pixel for tracking_pixel. Omitting or guessing it fails the create with Template not found against the trigger node. They are source_webhook templates and are not in the destination catalog (cdp-function-templates-list is type=destination), so don’t try to discover them there. Each needs inputs.event and inputs.distinct_id wrapped in {value: ...}, and the right values differ per trigger type because a different request reaches the template:
  • webhook — a POST whose body you control: "inputs": { "event": { "value": "{request.body.event}" }, "distinct_id": { "value": "{request.body.distinct_id}" } }.
  • manual — the “trigger manually” button POSTs {user_id, $variables}, so the body carries no event: use the fixed literal "inputs": { "event": { "value": "$workflow_triggered" }, "distinct_id": { "value": "{request.body.user_id}" } }. Pointing event at {request.body.event} here makes every manual run return 400 (the source template rejects an empty event) while the UI still shows a success toast, so the workflow silently never fires.
  • tracking_pixel — a bodyless GET, so read query params: "inputs": { "event": { "value": "{request.query.ph_event}" }, "distinct_id": { "value": "{request.query.ph_distinct_id}" } }. Body references resolve empty here and the pixel still returns its 200 GIF, so every hit is dropped with no error to retry on.
• batch — { "type": "batch", "filters": { "properties": [<cond>] } }. The audience: person-property conditions and/or cohort references. No event/action filters (silently dropped, so rejected). Does not fire on enable — dispatch a one-off broadcast with workflows-run-batch, or make it recurring with workflows-schedule-create (attaches an RRULE schedule; each firing re-broadcasts to this same config.filters.properties audience). A recurring broadcast is a batch trigger plus a schedule. Editing config.filters pauses any schedule attached to it, since the confirmed recipient count no longer holds - preview again and re-create the cadence.
• schedule — { "type": "schedule" }. One person-less run per occurrence, for jobs that act on their own (for example a “Create AI task” step). Attach the cadence with workflows-schedule-create; no audience preview is needed. Changing this trigger to batch pauses any schedule already attached, because that cadence was never sized against an audience - re-create it after the blast-radius preview.
• internal-event (flag-gated) — { "type": "internal-event", "filters": { "source": "internal-events", "events": [{ "id": "<event>", "type": "events" }], "properties": [<cond>] } }. Fires once for each matching event on the internal-events stream; filters.events must name at least one allowed event id. Runs have no associated person, so person-dependent steps are unavailable. Test-run with an event named in filters.events and no person; any other event name is skipped at the trigger. The Slack trigger is this with $slack_message_received in filters.events: the run’s event carries properties integration_id, channel, channel_type, slack_team_id, user, bot_id, app_id, subtype, text, ts, thread_ts, is_thread_reply, is_ext_shared_channel, and slack_event (the raw Slack payload). A workflow leaving draft must include one exact channel property filter whose value contains one or more channel IDs; several IDs match any listed channel. The GitHub trigger uses $github_event_received and requires exact repository and event_type filters.

Trigger masking (throttling an event trigger)

trigger_masking is a top-level workflow field (not an action) that throttles an already-matching event trigger — it dedups/samples firings, it does not decide who enters.

• hash — HogQL template defining the dedup key. "{person.id}" = once per person.
• ttl — seconds to suppress repeats of the same hash (60–94608000).
• threshold? — fire once per N matches of the same hash (a sampler: N=3 fires on the 1st, 4th, 7th…). Omit to fire once then suppress within ttl.
• Don’t send bytecode — compiled server-side from hash.

Condition shape (<cond>)

Property conditions used in trigger/action filters, branch conditions, and conversion:

type is event | person | group. Never include bytecode — the server compiles it.

Edges

• type: "continue" — fall-through: the sequential next step, or the no-match path out of a conditional_branch. For a wait_until_condition it is the max_wait_duration timeout path.
• type: "branch" — requires index, matching config.conditions[index] on a conditional_branch. A wait_until_condition resolves (its condition matches or an events entry fires) out the branch edge at index: 0.
• Every non-exit node needs a reachable next action via an outgoing edge, or execution fails with “No next action found”.
• A conditional_branch with N conditions typically has N branch edges (index: 0..N-1) plus one continue edge for the no-match path.
• A wait_until_condition needs a branch edge at index: 0 (resolution) and a continue edge (timeout). Without the index: 0 branch it only ever advances on timeout, never on the event/condition firing.

function* inputs

Inputs are keyed by the template’s input schema, each wrapped in {value: ...}:

• Wrap values in {value: ...}. A flat string won’t enable templating.
• Templating uses single-curly {person.x} / {event.x} inside the value string. Liquid-style {{ ... }} is rejected on hog-templated fields (“Placeholders are not allowed in this context”) — the only fields that accept Liquid are ones whose input schema declares templating: liquid (the email input on function_email does; most others don’t).
• Dictionary input values are template strings too — write booleans/numbers as single-expression templates: "{true}", "{42}", which evaluate to the typed value.
• Required inputs must be present, or create fails with “This field is required”.

Discovering function templates (do this, don’t guess)

The set of available function templates and their required inputs is live data, not something to hardcode — it changes as integrations are added. For a function node:

1. cdp-function-templates-list (filter type=destination) to find the right template and its id.
2. cdp-function-templates-retrieve with that id to read its inputs_schema — the exact keys, types, and which are required.
3. Build inputs from that schema. A template_id not in the live list fails with “Template not found”.

function_email, function_sms, and function_push are the exception — their template_id is the fixed literal template-email / template-twilio / template-native-push, so you don’t look the template_id up, and you can omit it entirely: the server infers the literal from the step type. A saved email template’s UUID goes in template_uuid alongside the literal, never in template_id (a UUID sent as template_id is moved into template_uuid automatically). For function_email, referencing a template means you only author from/to: the server materializes the template’s body at save (see the action-types table). function_push still has variable inputs (notably channels), so retrieve its inputs_schema even though the id is fixed.

function_push worked example

Retrieve template-native-push with cdp-function-templates-retrieve for the full inputs_schema (it has many optional Android/iOS keys), but the core shape is:

• channels is an integration_multi input: its value is an array of integration id numbers (e.g. [6, 7]), not objects. Find the FCM/APNs integration ids with integrations-list (look for kind firebase / apns); at least one is required or the send throws “No push channel configured”.
• Templating differs per input. body is liquid — interpolate with {{ person.x }} / {{ event.x }} (double braces) and set "templating": "liquid". title and the other string inputs are hog — use {event.x} / {person.x} (single braces). The wrong brace style leaves the expression as a literal.
• Required: distinctId, channels, title. Optional: body, image, data, ttlSeconds, android_*, ios_* (retrieve the inputs_schema for the full set).
• Never hand-author bytecode — the server compiles it from value. Omit order too: the editor lays fields out in the template’s inputs_schema order (fixed and consistent), not by the order on your inputs, so leaving it off doesn’t change the form. Push has no delivered/opened/clicked signal (FCM/APNs respond synchronously), so a successful send means “accepted for delivery”, nothing more.

Duration strings (delay_duration, max_wait_duration)

Must match ^\d*\.?\d+[dhms]$ — a number plus unit s | m | h | d. Examples: 30s, 30m, 2h, 1d, 1.5d (=36h).

• No ISO-8601. Fractions are allowed in every unit.
• Per-unit caps are silently clamped: s≤60, m≤60, h≤24, d≤30. Max total 30d. Use the larger unit (90m → use 1.5h) to avoid surprise clamping.

Waiting until a date (delay_until)

A delay waits either a fixed span or until a date carried by the person or the event. Use delay_until when the date differs per person, which a duration cannot express (a trial expiry, a renewal date, a booked appointment).

• Exactly one of delay_duration and delay_until. Both together are rejected; so is neither.
• expression is HogQL resolving to a datetime. An ISO string, a HogDateTime, and unix seconds all resolve to the same instant, so a stored date works whichever shape the customer set it in. A bare number is read as seconds: a millisecond timestamp (what Date.now() and most SDKs produce) is rejected rather than read as a date tens of thousands of years out. Divide it by 1000 in the expression, or store the date as an ISO string.
• offset shifts that instant and is signed: ^-?\d*\.?\d+[dhms]$. -1d is a day before the date, 2h is two hours after. Omit it to wait for the date itself. Keep the arithmetic here rather than in the expression, so the builder can still read the step back as a property plus an offset.
• Unlike delay_duration, an offset is not clamped per unit: -45d means 45 days, not 30. max_delay_duration bounds the wait instead.
• timezone, use_person_timezone and fallback_timezone work as they do on wait_until_time_window, and decide which zone a date with no offset of its own is read in (a bare 2026-03-01, or 2026-03-01T09:00:00). A date that states an offset, a HogDateTime, and unix seconds are absolute and ignore them. Default UTC, so a date-only value means midnight UTC unless you set a zone.
• max_delay_duration caps how far past the step’s start the wait may run (default 30d, same duration rules as above). It exists so a far-future date cannot park a run indefinitely.
• Never send bytecode. The server compiles the expression at save time and discards anything the client sent. A broken expression fails the save with the parse error.
• The expression is re-read on every wake, not only on entry, and the only wake a parked delay schedules is the instant it computed. So a date that moves further out is honored: the run wakes at the old instant and parks again to the new one. A date that moves closer is not: nothing wakes the run early, so it waits for the original instant and then continues at once, later than the new date asked for.
• A date that cannot be resolved aborts the run whatever on_error says, because a wait that cannot work out when to act has nothing safe to fall through to.
• A person property is person.properties.<key>; an event property is properties.<key>, with no event. prefix. The expression runs against the same globals as a filter, where event is the event’s name, so event.properties.<key> resolves to nothing and aborts the run.
• The builder writes those two shapes (bracketed when the key is not a bare identifier). Any other expression saves fine but shows in the editor as a read-only custom expression instead of a property pick.

Conversion & exit condition

• exit_condition: exit_only_at_end (default), exit_on_conversion, exit_on_trigger_not_matched, exit_on_trigger_not_matched_or_conversion.
• The …conversion variants require a conversion goal with two slots plus a window:
  • filters — property conditions only, an array [{key, value, operator, type}, ...] (empty array = any event in the window converts).
  • events — event-based goals, [{ "filters": { "events": [{ "id": "<event>", "name": "<event>", "type": "events" }] } }].
  • window — how long after entry a conversion still counts, as a duration string ("7d", "12h", "30m", "45s"), max "365d". The preferred form.
  • window_minutes — deprecated: the same window in minutes, not seconds, max 129600 (90 days). Set window or window_minutes, not both. Omit both (or null) for the default 90-day window.
• An event goal goes in events, never in filters. An event object stuffed into filters is invisible to the conversion matcher and breaks the conversion picker. Without a goal the …conversion exit is a silent no-op. Server compiles the bytecode.

Pre-submit checklist

• Not done: Exactly one type: "trigger" action; usually exactly one exit.
• Not done: Every action type and config matches a row above (no types outside the supported set).
• Not done: on_error is only continue or abort.
• Not done: function_email.template_id == "template-email", function_sms.template_id == "template-twilio", function_push.template_id == "template-native-push".
• Not done: A webhook / manual trigger sets template_id == "template-source-webhook" (a tracking_pixel uses "template-source-webhook-pixel") — these are built-in source templates, not catalog lookups.
• Not done: That trigger’s inputs.event / inputs.distinct_id match its own type: {request.body.*} for webhook, $workflow_triggered + {request.body.user_id} for manual, {request.query.ph_*} for tracking_pixel. The wrong pair saves fine and then fails at trigger time.
• Not done: Every non-exit node has an outgoing edge; branch edges have an index matching a condition.
• Not done: Every conditional_branch / wait_until_condition condition is wrapped: {filters: {properties: [...]}}, not {properties: [...]}.
• Not done: All durations match ^\d*\.?\d+[dhms]$ and dodge the silent per-unit clamp.
• Not done: Every delay sets exactly one of delay_duration and delay_until, and no delay_until carries hand-written bytecode.
• Not done: Function inputs are {key: {value: ...}}; no hand-written bytecode anywhere; no top-level trigger field set.