Triggers

ProxifAI has two distinct trigger systems, and both target the same internal platform event bus but enter from different ends:

System	Owned by	Configures	Fires
Workflow triggers	The workflow itself (triggers: block in YAML or DB)	Which events / schedules / manual inputs start this workflow	The workflow it’s defined on
Trigger rules	Org-level rule engine (trigger_rule table)	Event filter + action — works across workflows, agents, issues, webhooks	One of four action types

Use workflow triggers when you want a single workflow to react to events. Use trigger rules when you want one event to fan out to multiple actions, or you want to route to non-workflow targets like dispatching an agent or auto-creating an issue.

Workflow triggers

Defined in the workflow’s YAML under the triggers: key. The schema is parsed in internal/workflows/loader.go into proxifaiTrigger:

name: ci
type: ci

triggers:
  - type: event
    event: git.push
    branches: [main, "release/*"]
    paths: ["src/**", "go.mod"]

  - type: schedule
    cron: "0 9 * * 1-5"

  - type: manual
    inputs:
      environment: { type: select, options: [staging, production], default: staging }
      dry_run:     { type: boolean, default: true }

nodes: [...]
edges: [...]

Field	Applies to	Meaning
type	all	event | schedule | manual
event	event	Built-in event name (see catalog below); ProxifAI will register this workflow as a listener
cron	schedule	Five-field cron expression — the workflow scheduler runs in-process and converts each tick into an execution
branches, paths	event	Filters applied before firing — only git.push / pr.* events with a matching branch and changed path proceed
inputs	manual	Schema for the input form on pfai workflow run and the Run Workflow dialog

When a workflow has any event trigger, the loader auto-upgrades any start node to an event_trigger node so the event payload becomes available as graph input.

Trigger rules

A trigger rule is a row in the trigger_rule table. Where workflow triggers fire one workflow, trigger rules let you say “when X happens, do Y” — and Y doesn’t have to be a workflow.

┌──────────────────┐        ┌─────────────────┐        ┌────────────────────┐
│ PlatformEvent    │  ───►  │ trigger_rule    │  ───►  │  ActionExecutor    │
│ {type, source,   │        │  filter:        │        │  - dispatch_agent  │
│  subject, data}  │        │   event_source  │        │  - create_issue    │
└──────────────────┘        │   event_type    │        │  - send_webhook    │
                            │   conditions    │        │  - dispatch_workflow│
                            └─────────────────┘        └────────────────────┘

Every published event flows through every active trigger rule for the org. Rules whose filter matches dispatch their action. Rules are evaluated independently — one event can match many rules.

The four action types

Action	What it does	Required action_config
dispatch_agent	Creates an AgentExecution row, mirrors it into the unified Flows view, and publishes a dispatch.DispatchMessage for the agent worker	agentId (required); prompt (optional — defaults to "Triggered by <type> event from <source>")
create_issue	Inserts a row into the Issue table	title, description, priority, teamId, projectId
send_webhook	Sends an outbound HTTP request	url, method (default POST), headers, body (templated)
dispatch_workflow	Runs a published workflow with the event payload as input	workflowId (required); inputs (optional)

Action implementations live in internal/triggers/executor.go.

Conditions

Beyond the event_source + event_type filter on the rule itself, you can attach a JSON ConditionGroup (evaluator.go) to gate matches further:

{
  "operator": "and",
  "rules": [
    { "field": "data.priority", "operator": "eq",       "value": "urgent" },
    { "field": "data.teamId",   "operator": "eq",       "value": "team_42" },
    { "field": "subject",       "operator": "regex",    "value": "^auth/" }
  ]
}

Field paths	Operators
type, source, subject, orgId, timestamp, data.<nested.path>	eq, neq, contains, not_contains, gt, lt, regex

The data.<path> form drills into the nested JSON payload using dot notation. Rules combine via and/or; default is and.

Built-in event catalog

Seeded by SeedBuiltinEventTypes (seed_event_types.go) on every boot — safe to call repeatedly.

Category	Event name	Source	Fires when
Issues	issue.created	proxifai	A new issue is created
Issues	issue.updated	proxifai	Any issue field changes — status, priority, assignee, labels, sprint
Issues	issue.description_changed	proxifai	An issue description is edited; payload includes the full new text
Issues	issue.status_changed	proxifai	Status transitions (e.g. todo → in_progress → done)
Issues	issue.assigned	proxifai	Assigned or reassigned to a user or AI agent
Issues	comment.created	proxifai	A comment is posted on any issue
Code	git.push	proxifai	Code is pushed to any branch; payload includes commit SHA + changed files
Code	pr.created	proxifai	A pull request is opened
Code	pr.merged	proxifai	A pull request is merged
Code	pr.review_requested	proxifai	A reviewer is requested on a PR
CI/CD	pipeline.completed	proxifai	A pipeline finishes successfully
CI/CD	pipeline.failed	proxifai	A pipeline fails — payload includes failed step + error
Agents	agent.completed	proxifai	An agent execution finishes successfully
Agents	agent.failed	proxifai	An agent execution fails (timeout, crash, error)
External	webhook.*	external	Any incoming webhook — narrow with the source field (e.g. sentry, stripe, pagerduty)
External	webhook.alert	external	Webhook events classified as alerts (severity: info, warning, error, critical)
Tickets	ticket.created	proxifai	A new support ticket is created

Each builtin event ships with a JSON-Schema payload definition and a sample payload, surfaced in the trigger UI for autocomplete.

To add custom event types, create rows in the EventType table with isBuiltin = false (or use pfai event-type create).

Managing trigger rules from the CLI

pfai trigger ls                                # all rules in this org
pfai trigger view rule_42
pfai trigger create --name "Auto-triage urgent" \
                    --event-source proxifai --event-type issue.created \
                    --action dispatch_agent --action-config '{"agentId":"triage-agent"}'
pfai trigger toggle rule_42                    # enable / disable
pfai trigger test rule_42 --payload @sample.json  # synthetic event, no side effects
pfai trigger executions rule_42                # history of matches and dispatches
pfai trigger delete rule_42

Full CLI surface lives in internal/pfai/cmd/trigger.go.

Special-purpose triggers

Beyond the generic rule engine, two trigger types have first-class implementations because they need richer semantics than the rule evaluator can express:

• Comment triggers (internal/triggers/comment_trigger.go) — fire on issue and PR comments matching @<agent-name> mentions, dispatching that agent with the comment context.
• Slack triggers (internal/triggers/slack_trigger.go) — fire on Slack events from connected workspaces (slash commands, mentions in channels). Configured via the Slack integration page.

Both are layered on top of the same PlatformEvent bus — they’re more convenient surfaces, not separate runtimes.

Webhooks vs trigger rules

These are easy to confuse. They’re complementary:

	Inbound webhook	send_webhook trigger rule
Direction	External system → ProxifAI	ProxifAI → external system
Configured under	Integrations → Webhooks	Triggers → action_type=send_webhook
Fires	A webhook.* platform event you can react to with rules or workflows	An outbound HTTP request when an internal event matches the rule
URL	Generated by ProxifAI, given to the external service	Provided by you, called when the rule matches

To bridge an external system into your automation, register an inbound webhook so its requests become webhook.<source> events, then add a trigger rule (or workflow YAML trigger) that listens for webhook.alert (or webhook.<source>) and dispatches your action.

See Webhooks for the full inbound webhook spec.

See also