Workflows

Workflow Triggers

Define when and how workflows start executing

Triggers are the entry points of workflows. They define what event causes the workflow to start. Every workflow must have exactly one trigger node.

Trigger Types

ticket_created

Fires when a new ticket is created. Access full ticket data, customer profile, and initial message.

Use cases: Auto-assign, send acknowledgment, route to queues

ticket_updated

Fires when any field on a ticket changes. Previous values available in trigger.data.

Use cases: Sync to external systems, log audit trail, notify stakeholders

ticket_status_changed

Fires when status changes (open, pending, solved, closed).

Use cases: Send resolution confirmation, escalate reopened tickets, archive on close

ticket_assigned

Fires when a ticket is assigned or reassigned.

Use cases: Notify assignee, update task trackers, log assignment history

message_received

Fires when a new inbound message is added to a ticket.

Use cases: Auto-respond, detect urgent keywords, update status on reply

schedule

Fires on a recurring schedule using cron expressions.

Use cases: Daily SLA reports, weekly cleanup, nightly sync

Common patterns:

ExpressionMeaning
0 * * * *Every hour
0 9 * * *Daily at 9 AM
0 9 * * 1Weekly Monday 9 AM
0 0 1 * *Monthly on the 1st

webhook

Fires when an external system calls the workflow's unique webhook URL.

Use cases: Third-party integrations, custom event sources, external monitoring

Webhook URL format: https://app.keva.support/api/webhooks/workflow/{workflow-id}

manual

Fires only when explicitly triggered by a user or API call.

Use cases: One-off operations, testing, admin-initiated processes

Configuring Triggers

  1. Click the trigger node
  2. Select trigger type from dropdown
  3. Configure type-specific options (cron expression, etc.)
  4. Set a descriptive label

Trigger Data Access

trigger: {
  type: 'ticket_created',
  timestamp: '2024-03-15T10:30:00Z',
  data: { /* type-specific */ }
}

Use in templates: {{trigger.type}}, {{trigger.timestamp}}

Multiple Workflows

Multiple workflows can share the same trigger type. They execute in parallel independently.

Rate Limiting

  • Webhook: 100 requests/minute per workflow
  • Schedule: Minimum 1-minute interval
  • Events: Deduplicated within 1-second window

Debugging

Execution History

View recent executions in the workflow detail page under the Executions tab.

Testing

  1. Set trigger to manual during development
  2. Run manually with test data
  3. Switch to desired trigger for production

Best Practices

  1. Be specific: Use ticket_status_changed over ticket_updated when possible
  2. Add conditions early: Filter non-matching tickets right after trigger
  3. Consider timing: Schedule triggers for off-peak hours
  4. Test first: Use manual trigger before enabling event-based triggers

Next Steps