Triggers

Overview#

Every workflow has a trigger type that determines how it starts. Flow supports four trigger types: manual, API, webhook, and scheduled. The trigger type is set when the workflow is created and can be changed later.

Manual Trigger#

Manual triggers are started from the dashboard or by calling the execute endpoint directly. They are useful for ad-hoc workflows, testing, and one-off processes.

curl -X POST http://localhost:8009/api/v1/flows/{flow_id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "message": "I need to renew my trade license",
      "citizen_id": "CIT-2024-001"
    },
    "trigger": "manual"
  }'

API Trigger#

API triggers are designed for programmatic invocation from other systems. External applications call the execute endpoint with input data, and the workflow processes it end-to-end.

curl -X POST http://localhost:8009/api/v1/flows/{flow_id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "application_id": "PERMIT-2024-0892",
      "applicant_name": "Ahmed Al Mansoori",
      "permit_type": "commercial"
    },
    "trigger": "api"
  }'

API triggers are the most common choice for production workflows, as they integrate naturally with government portals, citizen service platforms, and internal tools.

Webhook Trigger#

Webhook triggers expose a unique URL that external systems can POST to. When the webhook receives data, it automatically starts a workflow run with the payload as input.

Webhook URLs follow the pattern:

POST /api/v1/flows/{flow_id}/webhook

This is useful for event-driven architectures where external systems (document management, CRM, ticketing) need to kick off workflows when events occur.

curl -X POST http://localhost:8009/api/v1/flows/{flow_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "event": "document_uploaded",
    "document_id": "DOC-2024-1234",
    "uploaded_by": "user@ministry.gov"
  }'

Scheduled Trigger#

Scheduled triggers run workflows on a cron-based schedule. They are configured with a cron expression that determines execution frequency.

Common scheduling patterns for government workflows:

Execution Response#

Regardless of trigger type, every workflow execution returns a run object:

{
  "id": "run-a1b2c3",
  "flow_id": "f1a2b3c4...",
  "flow_name": "Citizen Inquiry Router",
  "status": "completed",
  "trigger": "api",
  "steps": [
    {
      "step_id": "classify",
      "step_name": "Classify Inquiry",
      "step_type": "llm_call",
      "status": "completed",
      "output_data": {"category": "permit", "confidence": 0.94},
      "duration_ms": 850
    }
  ],
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:02Z",
  "duration_ms": 1800
}

Run Statuses#