Workflow Triggers

Triggers determine when and how your workflows execute. Every workflow must have exactly one trigger node as its first node. The trigger produces the initial data that flows downstream through the rest of the workflow.

Strongly AI provides 16 trigger types covering a wide range of execution patterns, from HTTP-based triggers to time-based schedules, file system monitoring, and event-driven architectures. This page covers the most common ones; the full list is in the builder's Triggers category and the Workflows Overview.

---

Webhook

Trigger a workflow over HTTP. Calls are authorized with a Strongly REST API key, or -- for external services like GitHub, Stripe, and Slack -- an HMAC signature using a shared secret. Unauthenticated calls are never accepted.

Use Cases

• GitHub push/pull request event processing
• Stripe payment and subscription notifications
• Slack message and interaction handling
• Custom webhook integrations from any service

Authorization

Method	How it works
REST API key	X-API-Key header with the workflows:execute scope, like every REST endpoint; runs as the caller
External HMAC signature	Provider-specific signature using the configured secret; runs as the workflow owner

Configuration

Setting	Description	Required
Webhook Provider	Signature verification scheme: GitHub, Stripe, Slack, or Generic HMAC (default: Generic)	Yes
Webhook Secret (HMAC)	Shared secret for external HMAC signature verification. Needed only when external signed services call the webhook; leave empty for an API-key-only webhook. Stored encrypted	No
Previous Secret (rotation)	Set during secret rotation: the old secret is also accepted so in-flight callers are not broken. Remove once all callers use the new secret	No
Allowed Events	Filter specific event types per provider (empty allows all)	No
IP Whitelist	Restrict access to specific IP addresses or CIDR ranges	No
Max Body Size (bytes)	Maximum request body size (default: 1MB, max: 10MB)	No
HTTP Method	POST, PUT, GET, or DELETE (default: POST; webhooks carry a JSON body that is HMAC-signed, so POST is the secure default)	Yes
Require Timestamp	Require a timestamp on requests for replay protection (default: false)	No
Max Timestamp Age (seconds)	Maximum accepted timestamp age (default: 300)	No
Rate Limit (per minute)	Maximum requests per minute (default: 10)	No
Rate Limit (per hour)	Maximum requests per hour (default: 100)	No

Provider-Specific Signature Verification

Each provider uses its own signature header:

Provider	Signature Header
GitHub	X-Hub-Signature-256
Stripe	Stripe-Signature (with timestamp)
Slack	X-Slack-Signature
Generic	X-Webhook-Signature

Security Features

The webhook trigger includes the following security measures:

• Authorized calls only, never unauthenticated
• HMAC verification with timing-safe comparison and secret rotation support
• Optional replay protection via timestamp validation
• Per-webhook rate limiting (configurable)
• Request size limits and optional IP whitelisting with CIDR support
• Generic error messages to prevent detail leakage; secrets are never logged

Outputs

Field	Type	Description
event	string	Event type (for example, push)
payload	object	Request payload
headers	object	Request headers
timestamp	string	ISO 8601 timestamp
provider	string	Webhook provider (github, stripe, slack, generic)

Execution metadata also records success, signatureVerified, processedAt, and requestId.

Webhook URL Pattern

/api/v1/webhooks/{workflowId}

Signature Verification

The HMAC secret is only needed when external signed services (GitHub, Stripe, Slack, or generic HMAC callers) will call this webhook. When you use it, choose a strong random value; it is stored encrypted.

---

Schedule

Trigger workflows on a time-based schedule. Scheduled workflows are deployed as scheduled jobs.

Use Cases

• Daily report generation
• Periodic data synchronization
• Scheduled cleanup and maintenance tasks
• Batch processing jobs on recurring intervals

Schedule Types

1. Interval-Based

Run at a fixed interval specified in minutes (1 to 10,080 minutes / 7 days):

Interval	Example Use Case
Every 5 minutes	Real-time monitoring
Every 60 minutes	Hourly data aggregation
Every 360 minutes	Periodic cleanup

2. Daily Execution

Run once per day at a specific time in 24-hour format (e.g., 09:00).

3. Cron Expression

Use standard cron syntax for advanced scheduling:

# Every weekday at 9 AM
0 9 * * 1-5

# First day of every month at midnight
0 0 1 * *

# Every 30 minutes during business hours
*/30 9-17 * * 1-5

# Quarterly on the 1st at 6 AM
0 6 1 */3 *

Cron Format Reference

+-------------- minute (0 - 59)
| +------------ hour (0 - 23)
| | +---------- day of month (1 - 31)
| | | +-------- month (1 - 12)
| | | | +------ day of week (0 - 6) (Sunday=0)
| | | | |
* * * * *

Configuration

Setting	Description	Required
Schedule Type	Interval, Daily, or Cron (default: Daily)	Yes
Interval (minutes)	Run frequency when using interval mode (1-10,080; default: 60)	Conditional
Daily Time	Time in 24-hour format when using daily mode (default: 09:00)	Conditional
Cron Expression	Standard cron expression when using cron mode	Conditional
Timezone	Execution timezone: UTC, Eastern, Central, Pacific, London, or Tokyo (default: UTC)	Yes
Enabled	Whether the schedule is active (default: true)	No

Outputs

Field	Type	Description
triggered	boolean	Whether the schedule fired
nextRun	string	ISO 8601 timestamp of the next scheduled run
scheduleType	string	The schedule type used (interval, daily, or cron)

Execution metadata also records success, processedAt, timezone, and executionId.

Timezone Configuration

Always specify the correct timezone for scheduled workflows. The schedule executes based on the configured timezone, which may differ from your local time or server time.

---

REST API Trigger

Expose a workflow as an authenticated REST API endpoint with role-based access control and input validation.

Use Cases

• Custom API endpoints for internal microservices
• Mobile and web application backends
• Third-party integration endpoints
• Synchronous request-response workflows

Configuration

Setting	Description	Required
API Endpoint Path	URL path for the API (e.g., /api/v1/my-workflow; default: /api/workflow)	Yes
HTTP Method	POST, GET, PUT, DELETE, PATCH, or Any Method (default: POST)	Yes
Require Authentication	Whether callers must be authenticated	No (default: true)
Allowed Roles	Roles permitted to call the endpoint: owner, admin, user, viewer (default: owner, admin, user)	No
Expected Inputs	Input field definitions with type and validation	No
Default Query Parameters	Default query parameters as JSON	No

Expected Inputs Schema

Define expected input fields with validation:

Property	Description
Name	Field name (e.g., userId)
Type	Data type: string, number, integer, boolean, array, object
Required	Whether the field is mandatory
Default	Default value if not provided
Description	Field description for API documentation

Outputs

Field	Type	Description
method	string	HTTP method
body	object	Request body
query	object	Query parameters
headers	object	Request headers
params	object	URL path parameters
user	object	Authenticated user info

Execution metadata also records success, authenticated, processedAt, requestId, and endpoint.

Response Handling

Use the webhook-response destination node to send structured responses back to the API caller. The workflow output returned by the webhook-response node becomes the HTTP response body.

---

Chat Trigger

Trigger workflows from chat and conversational interfaces with automatic conversation history management.

Use Cases

• Conversational AI assistants
• Customer support chatbots
• Interactive Q&A workflows
• Multi-turn dialogue systems

Configuration

Setting	Description	Required
Session ID Field	Input field name containing the session/conversation ID	No (default: sessionId)
Message Field	Input field name containing the message content	No (default: message)
Include History	Include previous messages in the conversation	No (default: true)
Max History Length	Maximum number of history messages to include (1-50)	No (default: 10)

Inputs

Field	Type	Required	Description
message	string	Yes	Chat message content
sessionId	string	No	Session/conversation identifier
userId	string	No	User identifier

Outputs

Field	Type	Description
message	string	Message content
sessionId	string	Session/conversation ID
history	array	Previous conversation messages
currentMessage	object	Current message with role and content

---

Email Trigger

Trigger workflows when new emails arrive by monitoring an IMAP inbox. Supports filtering by search criteria and automatic mark-as-read to prevent reprocessing.

Use Cases

• Automated email processing and routing
• Support ticket creation from incoming emails
• Invoice and attachment extraction
• Email-driven approval workflows

Configuration

Setting	Description	Required
IMAP Host	IMAP server hostname (e.g., imap.gmail.com)	Yes
Port	IMAP port (993 for SSL, 143 for non-SSL)	No (default: 993)
Use SSL	Connect using SSL/TLS	No (default: true)
Username	Email account username	Yes
Password	Email account password or app-specific password (encrypted)	Yes
Mailbox	Mailbox/folder to monitor	No (default: INBOX)
Search Criteria	IMAP search filter	No (default: Unread)
Mark as Read	Mark fetched emails as read to avoid reprocessing	No (default: true)
Max Emails	Maximum emails to fetch per trigger (1-100)	No (default: 10)

Search Criteria Options

Value	Description
UNSEEN	Unread emails only
ALL	All emails
FLAGGED	Flagged/starred emails
RECENT	Recent emails
SENTON	Today's emails

Outputs

Field	Type	Description
emails	array	Array of email objects with id, subject, from, to, bodyText, attachments
count	number	Number of emails fetched
mailbox	string	Mailbox name that was searched

Execution metadata also records success and emailsFetched.

---

Form Trigger

Accept public form submissions with configurable fields, file uploads, reCAPTCHA protection, and rate limiting.

Use Cases

• Contact and inquiry forms
• File upload portals
• Survey and feedback collection
• Support ticket submission
• Application and registration workflows

Configuration

Setting	Description	Required
Form ID	Unique identifier for this form	No (default: form)
Form Title	Display name for the form	No (default: Contact Form)
Description	Form description or instructions	No
Enable CAPTCHA	Require reCAPTCHA v3 verification	No (default: true)
reCAPTCHA Secret Key	Google reCAPTCHA v3 secret key (encrypted)	Conditional
CAPTCHA Score Threshold	Minimum reCAPTCHA score (0.0-1.0)	No (default: 0.5)
Rate Limit (per hour)	Maximum submissions per hour from same IP (1-1000)	No (default: 10)
Max File Size (MB)	Maximum file upload size in megabytes (1-100)	No (default: 10)
Form Fields	Field definitions with validation rules	No
Validation Rules	Custom validation rules per field (JSON)	No
Success Message	Confirmation text after submission	No
Redirect URL	Post-submission redirect URL	No
Send Email Notification	Send email on form submission	No (default: false)
Email To	Notification recipient email address	Conditional

Supported Field Types

Type	Description
text	Single-line text input
email	Email address with format validation
number	Numeric input
boolean	Checkbox
file	File upload
textarea	Multi-line text
select	Dropdown selection
date	Date picker
url	URL with format validation
tel	Phone number

Each field supports a name, label, required flag, and placeholder text.

CAPTCHA Protection

The form trigger supports Google reCAPTCHA v3, which provides score-based bot detection without user interaction. Configure a score threshold between 0.0 and 1.0 to control sensitivity. Obtain reCAPTCHA keys from Google reCAPTCHA Admin.

Outputs

Field	Type	Description
formId	string	Form identifier
submissionId	string	Unique submission identifier
fields	object	Submitted form field values
files	array	Processed uploaded files
submittedAt	string	ISO 8601 submission timestamp
ipAddress	string	Submitter IP address

Execution metadata also records success, captchaVerified, captchaScore, processedAt, and userAgent.

---

File Trigger

Trigger workflows based on local file system changes. Supports monitoring directories for created, modified, or deleted files with glob pattern matching.

Use Cases

• Process new files uploaded to a directory
• Detect configuration file changes
• Monitor data landing zones for new CSV/JSON files
• File integrity monitoring via hash comparison

Configuration

Setting	Description	Required
Watch Path	File or directory path to monitor	Yes
Operation	Check Changes, List Files, Get File Info, Get File Hash, or Watch Directory	Yes
Trigger On	File Created, File Modified, File Deleted, or Any Change	No (default: Any Change)

Operations

Operation	Description
Check Changes	Compare current state against previous state to detect changes
List Files	List all files matching the path and pattern
Get File Info	Get metadata for a specific file (name, size, timestamps)
Get File Hash	Compute hash of a file (MD5, SHA1, SHA256, SHA512)
Watch Directory	Create a snapshot of directory state for future comparison

Inputs

Field	Type	Description
watchPath	string	Path to file or directory to monitor
pattern	string	File pattern using glob syntax (e.g., *.csv)

Outputs (Check Changes)

Field	Type	Description
hasChanges	boolean	Whether changes were detected
triggeredFiles	array	Array of changed file objects

---

RSS Feed Trigger

Trigger workflows when new RSS or Atom feed items appear. Tracks previously seen items to process only new entries.

Use Cases

• News and content aggregation
• Blog post monitoring and notifications
• Competitor content tracking
• Automated content curation pipelines

Configuration

Setting	Description	Required
Feed URL	URL of the RSS or Atom feed	Yes
Max Items	Maximum items to fetch per trigger (1-100)	No (default: 20)
Only New Items	Only return items not seen in previous triggers	No (default: true)
Include Full Content	Include full article content when available	No (default: true)

Outputs

Field	Type	Description
items	array	Feed items with id, title, link, published, summary
count	number	Number of items returned
feedTitle	string	Title of the feed
feedUrl	string	URL of the feed that was fetched

---

SSE Trigger

Trigger workflows when Server-Sent Events are received from an external SSE endpoint. Supports automatic reconnection and event type filtering.

Use Cases

• Real-time event stream processing
• Live data feed consumption
• Server push notification handling
• Streaming API integration

Configuration

Setting	Description	Required
SSE Endpoint URL	URL of the SSE endpoint to connect to	Yes
Event Types	Comma-separated event types to listen for (empty listens to all)	No
Headers	Custom headers for the SSE connection (key-value pairs)	No
Auto Reconnect	Automatically reconnect on connection loss	No (default: true)
Reconnect Delay (ms)	Delay before reconnection attempt	No (default: 3000)

Outputs

Field	Type	Description
eventType	string	SSE event type
data	any	Parsed event data (JSON if valid, otherwise string)
eventId	string	SSE event ID

---

Error Trigger

Trigger a workflow when errors occur in other workflow executions. Enables centralized error handling, alerting, and recovery workflows.

Use Cases

• Centralized error logging and alerting
• Automated incident creation from workflow failures
• Error recovery and retry orchestration
• Severity-based escalation workflows

Configuration

Setting	Description	Required
Filter by Workflow IDs	Only trigger for errors from specific workflows (empty = all)	No
Filter by Node Types	Only trigger for errors from specific node types (empty = all)	No
Filter by Severity	Only trigger for specific severities: Warning, Error, Critical (empty = all)	No
Include Stack Trace	Include full error stack trace in output	No (default: true)

Outputs

Field	Type	Description
error	object	Error details with message, type, and severity
workflow	object	Workflow context with workflowId
node	object	Node context with nodeId
metadata	object	Additional error metadata

---

Multi-Modal Input

Accept mixed media types as workflow input, including text, images, audio, and files in a single request.

Use Cases

• AI workflows requiring multiple input types (text + image)
• Document processing with mixed media
• Multi-format data ingestion pipelines
• Interactive applications with diverse input types

Configuration

Setting	Description	Required
Accepted Types	Array of accepted media types (text, image, audio, file)	No (default: all)
Max File Size (MB)	Maximum file size in megabytes (1-100)	No (default: 10)
Max Items	Maximum number of input items (1-50)	No (default: 10)

---

Event

The Event trigger (event) starts a workflow from platform events such as workflow completed, workflow failed, AI model deployed or undeployed, data uploaded, add-on status changed, and marketplace app installed or uninstalled. Select which event types should trigger the workflow (leave empty to receive all), and optionally add custom event type names such as order.created; custom events can be emitted via the REST API at POST /api/v1/workflows/events. The trigger outputs the event type, event data, source, and timestamps.

---

Queue

The Queue trigger (queue) starts a workflow from a message queue backed by a REST API enqueue endpoint: callers submit messages to POST /api/v1/workflows/{workflowId}/enqueue and each message triggers an execution. You can cap concurrent executions from the queue (0 = unlimited) and enable priority processing so higher-priority messages are processed first. The trigger outputs the message, its priority, source, and enqueue/processing timestamps.

---

Agent Trigger

The Agent trigger (agent-trigger) sends a message to an agent endpoint and captures the streamed response, which makes it useful for scheduled agent heartbeats and agent-driven workflows. Configure the agent URL, the message to send (with {{variable}} substitution), a thread pattern that controls conversation grouping (daily, weekly, single, or per execution; default daily), and a response timeout (10-600 seconds, default 300). The trigger outputs the thread ID, the agent's response text, the tools it called, and the run duration.

---

Task Due

The Task Due trigger (task-due-trigger) fires when a platform task's due date is reached. You can filter which task firings start the workflow by subject kind, subject app, or assigned agent, and bound how many times a task must have fired before matching (for example, set a maximum fire count of 0 to fire only on a task's first activation). Leave all filters empty to match all due tasks within the workflow's tenant scope. The triggered workflow receives the full task object, including its description, subject reference, due date, recurrence, fire count, and tags.

---

Streaming Workflow Triggers

Streaming workflows use a separate trigger set from the batch palette. It includes the WebSocket trigger (websocket-trigger), which accepts real-time WebSocket connections for bidirectional audio and text streaming. See the streaming palette in the workflow builder for the full set.

---

Architecture Notes

Trigger Execution Model

Triggers are the entry point for every workflow execution. Each workflow has exactly one trigger node, and the trigger type determines how the workflow is invoked:

• Request-based triggers (webhook, REST API, chat, form, multi-modal input, queue) are invoked through the platform backend when an HTTP request arrives at the appropriate endpoint.
• Schedule triggers run on the configured schedule. When the schedule fires, the workflow executes.
• Polling triggers (email, RSS, file) check for new data at execution time and produce results for downstream nodes.
• Event-driven triggers (event, error, SSE, task due) react to events from the platform, other workflows, or external systems.

---

Common Patterns

Webhook Event Routing

Webhook Trigger (GitHub)
  -> Switch-Case (Route by event_type)
    -> [push] Process push event
    -> [pull_request] Process PR event
    -> [issues] Process issue event

Scheduled Batch Processing

Schedule Trigger (Daily at 2 AM)
  -> REST API Call (Fetch records)
  -> Loop (Process each record)
  -> MongoDB Destination (Update database)
  -> SMTP (Send completion report)

Form Submission Processing

Form Trigger (with CAPTCHA)
  -> MongoDB Destination (Store submission)
  -> SMTP (Send confirmation email)
  -> Webhook Response (Return success message)

Centralized Error Handling

Error Trigger (Filter: severity = critical)
  -> Switch-Case (Route by error type)
    -> [ConnectionError] Retry workflow
    -> [TimeoutError] Alert on-call team
    -> [default] Log to monitoring system

---

Troubleshooting

Webhook Not Triggering

• Verify the webhook URL matches the pattern /api/v1/webhooks/{workflowId}
• Confirm the caller is authorized: a valid REST API key, or (for external signed services) an HMAC secret matching what the service is configured with
• Check that the workflow is deployed and active
• If using IP whitelisting, verify the sender IP is in the allowed range
• Review execution logs for signature verification failures

Schedule Not Running

• Verify the workflow is deployed
• Confirm timezone settings are correct for the intended execution time
• Check that the enabled flag is set to true
• Review the workflow's run history in the Workflow Monitor
• Validate the cron expression syntax

REST API Returning Errors

• Verify authentication credentials and user roles match the allowedRoles configuration
• Check that the request body matches the expectedInputs schema
• Ensure the HTTP method matches the configured method
• Confirm the workflow is deployed and the endpoint path is correct

Email Trigger Not Processing

• Test IMAP connectivity with the configured host and port
• Verify credentials (use app-specific passwords for Gmail)
• Confirm SSL settings match the server requirements
• Check that the search criteria matches available emails
• Verify the mailbox name is correct

---

Next Steps

• Configure workflow nodes
• Test your workflows
• Deploy to production
• See workflow examples