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

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: POST /api/webhooks/workflow/<endpoint-path> — send the endpoint's secret in an X-Webhook-Secret header and a UUID in an Idempotency-Key header. If the workflow's steps act on a ticket, the JSON body must include ticketId (the ticket's 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

Multiple Workflows

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

Rate Limiting

  • Webhook: No enforceable request-rate guarantee yet across all valid-looking pre-authentication traffic. Local source applies a separate fail-closed 300-request/60-second bucket to the SHA-256 hash of one valid opaque endpoint ID before database or body work. Missing/failed Redis returns 503; a limited bucket returns 429 with Retry-After. This does not stop valid-looking random-ID rotation, provide per-source fairness or trusted IP attribution, prove WAF/DDoS or configured Redis, or establish deployed/live workflow behavior. The seven other selected API-key, widget, and intake limiter calls are also fail-closed at their route-specific boundaries; this is not universal or deployed enforcement.
  • 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 message_received with conditions instead of a broad trigger when you only care about part of a ticket's lifecycle
  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