This page documents the trigger system that initiates workflow execution in Sim. Triggers define how and when workflows start running, from manual user actions to automated webhook events and scheduled executions. This covers trigger types, resolution logic, configuration, and the different execution paths based on trigger source.
For information about the actual workflow execution process after a trigger fires, see Workflow Execution Engine. For deployment configuration that enables external triggers, see Deployment & Versioning.
The system supports multiple trigger types, each with distinct characteristics and execution paths. The core trigger type enumeration is defined as CoreTriggerType and used throughout the execution pipeline.
| Trigger Type | Usage Context | Requires Deployment | Authentication |
|---|---|---|---|
manual | Canvas editor "Run" button | No (draft state) | Session |
api | REST API calls to execute endpoint | Yes | API key / Session |
chat | Chat interface interactions | No (draft state) | Session |
webhook | Generic webhook receiver | Yes | Optional token |
schedule | Cron-based scheduled execution | Yes | N/A (internal) |
Additional trigger types exist for provider-specific webhook integrations, identified by provider name (e.g., slack, github, stripe, airtable, etc.). These use the same webhook infrastructure but apply provider-specific validation and payload formatting.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:39-57, apps/sim/stores/logs/filters/types.ts apps/sim/lib/workflows/executor/execution-core.ts128-131
When a workflow executes, the system must determine which block serves as the entry point. This process differs based on trigger type and workflow configuration.
Diagram: Trigger Block Resolution Logic
The system maps trigger types to execution kinds for block resolution:
TriggerUtils.findStartBlock() to locate blocks with matching trigger or triggerKind configurationresolveStartCandidates() to find all potential start blocks, then select the highest priority triggerSources: apps/sim/lib/workflows/executor/execution-core.ts222-246 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:783-858
The resolveStartCandidates() function categorizes trigger blocks into paths using the StartBlockPath enum:
Diagram: Start Block Path Taxonomy
Trigger Priority (Highest to Lowest):
The selectBestTrigger() function enforces constraints, such as allowing only one API Trigger per workflow and validating that non-legacy triggers have outgoing connections.
Sources: apps/sim/lib/workflows/triggers/triggers.ts apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:798-841
Trigger blocks store configuration in their subBlocks that defines input format, mock payloads, and trigger-specific settings.
Trigger blocks can define expected input fields using the inputFormat subblock:
For manual execution, test values are extracted from inputFormat and passed as workflow input.
External triggers (webhooks, schedules) can define mock payloads for manual testing:
mockPayload subblockThe function triggerNeedsMockPayload() determines whether to extract and use the mock payload, and extractTriggerMockPayload() retrieves it.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:769-857, apps/sim/lib/workflows/triggers/trigger-utils.ts
Each trigger type follows a distinct execution path through the system.
Diagram: Manual Execution Sequence
Manual execution (triggerType='manual') always uses draft state from normalized tables and supports SSE streaming for real-time console updates.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:616-656, apps/sim/app/api/workflows/[id]/execute/route.ts:498-841
Diagram: API Execution Paths
API execution supports two modes:
authType='api_key')X-Execution-Mode: async header)Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:178-323, apps/sim/background/workflow-execution.ts30-176
Diagram: Webhook Trigger Processing Pipeline
Webhook processing includes several provider-specific steps:
file or file[] outputs in trigger schemaSources: apps/sim/app/api/webhooks/trigger/[path]/route.ts:37-176, apps/sim/background/webhook-execution.ts95-605 apps/sim/lib/webhooks/processor.ts
Diagram: Schedule Trigger Lifecycle
Scheduled execution includes sophisticated error handling:
MAX_CONSECUTIVE_FAILURES (constant defined in system), schedule is automatically disabledSources: apps/sim/background/schedule-execution.ts285-566 apps/sim/lib/workflows/schedules/utils.ts
Chat execution (triggerType='chat') is similar to manual execution but includes:
Chat workflows locate trigger blocks by searching for blocks with trigger: 'chat' configuration.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:307-614
Throughout workflow execution, trigger information is preserved in the ExecutionMetadata structure:
This metadata:
triggerType in workflowExecutionLogs)The LoggingSession class creates trigger objects with this metadata for comprehensive execution tracking.
Sources: apps/sim/executor/execution/types.ts6-29 apps/sim/lib/logs/execution/logging-session.ts99-109 apps/sim/lib/logs/execution/logging-factory.ts10-20
When resuming a paused workflow (Human-in-the-Loop), the trigger resolution is bypassed entirely. The system uses the pendingQueue from the serialized snapshot instead of resolving a trigger block.
Sources: apps/sim/lib/workflows/executor/execution-core.ts217-228
The edge construction system prevents direct edges between trigger blocks to avoid ambiguous execution paths. This validation occurs during DAG building.
Sources: apps/sim/executor/dag/construction/edges.ts
For webhook triggers using credential sets, a single webhook path can map to multiple workflow instances, each with different credentials. The system processes each webhook sequentially:
Sources: apps/sim/app/api/webhooks/trigger/[path]/route.ts:64-176, apps/sim/lib/webhooks/processor.ts374-419
Workflows expose different trigger endpoints based on deployment status and trigger type configuration.
| Trigger Type | Endpoint Pattern | Requires Deployment |
|---|---|---|
| API | POST /api/workflows/:id/execute | Yes |
| Webhook (Generic) | POST /api/webhooks/trigger/:path | Yes |
| Webhook (Provider) | POST /api/webhooks/trigger/:path | Yes |
| Schedule | N/A (Internal) | Yes |
| Manual | POST /api/workflows/:id/execute (with session) | No |
| Chat | Chat interface (streaming) | No |
The webhook path is determined during deployment and stored in the webhook table with the relationship to deployment version.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts, apps/sim/app/api/webhooks/trigger/[path]/route.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.