Workflow Triggers

Relevant source files

• apps/sim/app/api/function/execute/route.test.ts
• apps/sim/app/api/function/execute/route.ts
• apps/sim/app/api/memory/route.ts
• apps/sim/blocks/blocks/grain.ts
• apps/sim/blocks/blocks/knowledge.ts
• apps/sim/blocks/blocks/memory.ts
• apps/sim/blocks/blocks/schedule.ts
• apps/sim/executor/dag/construction/paths.ts
• apps/sim/executor/handlers/function/function-handler.test.ts
• apps/sim/executor/handlers/function/function-handler.ts
• apps/sim/executor/utils/start-block.test.ts
• apps/sim/executor/utils/start-block.ts
• apps/sim/executor/variables/resolver.ts
• apps/sim/executor/variables/resolvers/block.test.ts
• apps/sim/executor/variables/resolvers/block.ts
• apps/sim/executor/variables/resolvers/reference.ts
• apps/sim/lib/core/security/input-validation.server.ts
• apps/sim/lib/core/security/input-validation.test.ts
• apps/sim/lib/core/security/input-validation.ts
• apps/sim/lib/execution/isolated-vm-worker.cjs
• apps/sim/lib/guardrails/validate_regex.ts
• apps/sim/lib/webhooks/provider-subscriptions.ts
• apps/sim/lib/webhooks/provider-utils.ts
• apps/sim/lib/webhooks/rss-polling-service.ts
• apps/sim/tools/function/execute.test.ts
• apps/sim/tools/function/execute.ts
• apps/sim/tools/function/types.ts
• apps/sim/tools/memory/add.ts
• apps/sim/tools/memory/delete.ts
• apps/sim/tools/memory/get.ts
• apps/sim/tools/memory/get_all.ts
• apps/sim/tools/memory/types.ts
• apps/sim/triggers/ashby/application_submit.ts
• apps/sim/triggers/ashby/candidate_delete.ts
• apps/sim/triggers/ashby/candidate_hire.ts
• apps/sim/triggers/ashby/candidate_stage_change.ts
• apps/sim/triggers/ashby/job_create.ts
• apps/sim/triggers/ashby/offer_create.ts
• apps/sim/triggers/ashby/utils.ts
• apps/sim/triggers/grain/highlight_created.ts
• apps/sim/triggers/grain/highlight_updated.ts
• apps/sim/triggers/grain/index.ts
• apps/sim/triggers/grain/item_added.ts
• apps/sim/triggers/grain/item_updated.ts
• apps/sim/triggers/grain/recording_created.ts
• apps/sim/triggers/grain/recording_updated.ts
• apps/sim/triggers/grain/story_created.ts
• apps/sim/triggers/grain/utils.ts
• apps/sim/triggers/grain/webhook.ts
• apps/sim/triggers/registry.ts

This document covers the trigger system that initiates workflow executions. Triggers are entry points that activate workflows in response to events such as webhook payloads, scheduled times, API calls, manual user actions, and external provider events (e.g., new emails or RSS updates).

For information about the execution engine that runs after triggers fire, see Workflow Execution Engine. For background job processing, see Background Execution & Job Queue.

---

Trigger Types Overview

The platform supports several primary trigger types, categorized by their activation mechanism and whether they require polling or push-based events.

Trigger Type	Activation Method	Key Implementation	Polling
Starter	Standard entry point (Chat, Manual, API)	resolveExecutorStartBlock	No
Webhook	External HTTP POST	apps/sim/app/api/webhooks/trigger/[path]	No
Schedule	Cron-based recurrence	apps/sim/blocks/blocks/schedule.ts	No
Email/RSS	Provider-specific events	apps/sim/lib/webhooks/rss-polling-service.ts	Yes
Manual/API	UI Button or REST call	apps/sim/blocks/blocks/api_trigger.ts	No

Sources: apps/sim/executor/utils/start-block.ts32-74 apps/sim/blocks/blocks/schedule.ts8-20 apps/sim/lib/webhooks/rss-polling-service.ts1-20

---

Trigger Architecture

The following diagram illustrates the flow from an external event to the resolution of a start block within the execution engine.

From External Event to Code Entity

Sources: apps/sim/executor/utils/start-block.ts32-74 apps/sim/lib/core/security/input-validation.ts50-160 apps/sim/executor/variables/resolver.ts39-93 apps/sim/lib/webhooks/provider-subscriptions.ts66-205

---

Starter and Start Block Resolution

The system uses resolveExecutorStartBlock to identify the correct entry point for a workflow based on the ExecutionKind ('chat', 'manual', or 'api') and whether the workflow is a child workflow apps/sim/executor/utils/start-block.ts13-35

Execution Logic

1. Candidate Identification: The engine scans all blocks and identifies those with triggerAllowed: true or specific trigger categories apps/sim/executor/utils/start-block.ts40-58
2. Path Classification: classifyStartBlockType determines the entry path (e.g., chat, webhook, api) based on block metadata and triggerModeEnabled apps/sim/executor/utils/start-block.ts85-91
3. Output Unified Construction: Regardless of the trigger source, the engine builds a UnifiedStartOutput. This includes input, conversationId, and files apps/sim/executor/utils/start-block.ts259-280
4. Input Coercion: Values passed into triggers are coerced based on the defined inputFormat. Supported types include string, number, boolean, object, and array apps/sim/executor/utils/start-block.ts136-170

Sources: apps/sim/executor/utils/start-block.ts1-280 apps/sim/lib/workflows/triggers/triggers.ts1-50

---

Webhook System

Webhooks allow external services to trigger workflows via HTTP. The system handles "push" webhooks through provider-specific subscriptions.

Webhook Security & Validation

• Path Validation: Every webhook trigger path is validated using validatePathSegment to prevent path traversal attacks apps/sim/lib/core/security/input-validation.ts50-160
• SSRF Protection: For triggers that involve outbound requests (like custom tool execution or proxying), validateUrlWithDNS resolves hostnames to IPs and blocks private/reserved ranges apps/sim/lib/core/security/input-validation.server.ts56-121

Provider Subscriptions

The system manages lifecycle subscriptions for external providers:

• Microsoft Teams: createTeamsSubscription uses the Microsoft Graph API to create chat message subscriptions with a max lifetime of 4230 minutes (~3 days) apps/sim/lib/webhooks/provider-subscriptions.ts66-185
• OAuth Integration: Subscriptions resolve owner credentials via getCredentialOwner and refreshAccessTokenIfNeeded before calling provider APIs apps/sim/lib/webhooks/provider-subscriptions.ts35-60

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts1-205 apps/sim/lib/core/security/input-validation.ts50-160 apps/sim/lib/core/security/input-validation.server.ts56-121

---

Scheduled Triggers

The ScheduleBlock allows workflows to run based on time intervals or Cron expressions.

Configuration Options

The block supports various frequencies via the scheduleType dropdown apps/sim/blocks/blocks/schedule.ts24-40:

• Minutes/Hourly: Simple interval-based execution apps/sim/blocks/blocks/schedule.ts43-60
• Daily/Weekly/Monthly: Time-of-day and day-of-week/month selectors apps/sim/blocks/blocks/schedule.ts63-115
• Custom (Cron): Supports standard cron syntax (e.g., 0 0 * * *) apps/sim/blocks/blocks/schedule.ts118-124
• Timezone Support: Users can specify a timezone, defaulting to the system's resolved timezone via Intl.DateTimeFormat apps/sim/blocks/blocks/schedule.ts147-198

AI-Assisted Scheduling

The cronExpression sub-block includes a wandConfig, allowing the AI Copilot to generate valid cron expressions from natural language descriptions like "every weekday at 9am" using a specialized system prompt apps/sim/blocks/blocks/schedule.ts125-143

Sources: apps/sim/blocks/blocks/schedule.ts8-215

---

Variable Resolution from Triggers

Triggers provide the initial context used by downstream blocks. The VariableResolver and BlockResolver handle these references.

Reference Handling

• Reference Detection: isReference identifies strings like <start_block.input> apps/sim/executor/variables/resolvers/block.ts37-47
• Path Navigation: resolveBlockReference parses path segments to extract specific nested data from the trigger payload apps/sim/executor/variables/resolvers/block.ts78-86
• Formatting for Code: When a trigger value is passed to a function block, formatValueForCodeContext ensures the literal is correctly escaped for JavaScript or Python apps/sim/executor/variables/resolvers/block.ts213-215

Backwards Compatibility

The handleBackwardsCompat method in BlockResolver ensures that legacy trigger output structures (specifically for response and workflow blocks) remain functional even if the internal schema evolves apps/sim/executor/variables/resolvers/block.ts106-147

Sources: apps/sim/executor/variables/resolvers/block.ts1-216 apps/sim/executor/variables/resolver.ts95-120

---

Trigger Execution Sequence

Sources: apps/sim/executor/utils/start-block.ts32-74 apps/sim/app/api/function/execute/route.ts1-102 apps/sim/tools/function/execute.ts72-103