Triggers Overview

Triggers are the starting point for every flow. They define how and when your flow executes, what data it receives, and how it responds. Think of triggers as the “on switch” that activates your intelligent agents and automation.

What is a Trigger?

A trigger is an event that starts your flow execution. When the trigger fires, it:

Starts the flow - Initiates the execution
Provides data - Passes information to the first step
Determines response mode - Synchronous or asynchronous
Handles the response - Returns results to the caller (if applicable)

Trigger Types

QuivaWorks offers several trigger types to suit different use cases:

Embed Triggers

Button, Form, ChatEmbed in your website or web app:

Button: Click to trigger
Form: Collect data and submit
Chat: Interactive conversation

Use for: Customer-facing interfaces

HTTP Request

Custom API EndpointTrigger via HTTP POST request:

Custom endpoint URL
Send JSON data
Receive JSON response

Use for: API integrations, webhooks from your app

Webhook

Receive External EventsAccept webhooks from other services:

Stripe payments
GitHub events
Slack messages
Any webhook-enabled service

Use for: External service integrations

Schedule

Run on ScheduleExecute at specific times or intervals:

One-time execution
Recurring: hourly, daily, weekly, monthly
Cron-like scheduling

Use for: Reports, maintenance, batch processing

Upload

Document UploadTrigger when files are uploaded:

PDFs, images, documents
Direct upload to endpoint
Process documents automatically

Use for: Document processing, OCR, data extraction

Email

Incoming EmailTrigger when email arrives:

Unique email address per flow
Full email content and attachments
Process automatically

Use for: Email automation, support tickets

Stream Triggers

Real-time Messages (Advanced)Trigger on stream messages:

Low-latency event processing
Message filtering by subject
High-throughput streams

Use for: Real-time data processing, event-driven architecture

Choosing the Right Trigger

Decision Framework

How to Choose a Trigger Type

Ask yourself:

Who/what starts the flow?
- User on website → Embed (Button/Form/Chat)
- External service → Webhook
- Your application → HTTP Request
- Time-based → Schedule
- User uploads file → Upload
- User sends email → Email
- Internal system event → Stream Triggers
Is it user-facing?
- Yes, users interact directly → Embed Triggers
- No, system-to-system → HTTP Request, Webhook, Stream
Does it need immediate response?
- Yes → Embed, HTTP Request, Webhook
- No → Schedule, Upload, Email (can be async)
How often does it run?
- Continuously (on-demand) → Embed, HTTP, Webhook, Upload, Email
- Scheduled → Schedule trigger
- Event-driven → Webhook, Stream
What data format?
- Form fields → Form Embed
- JSON → HTTP Request, Webhook
- File → Upload
- Email → Email trigger
- Stream message → Stream triggers

Common Use Cases by Trigger

Customer Service Automation

Best triggers:Chat Embed (Primary)

Embed chat widget on website
Customers interact in real-time
Agent responds immediately
Natural conversation flow

Email (Secondary)

[email protected]
Email triggers support flow
Agent processes and responds
Good for async support

Example:

Trigger: Chat Embed
↓
Customer Service Agent
- Tools: Knowledge Base, Order Lookup
↓
Respond to customer in chat

Lead Qualification

Best triggers:Form Embed (Primary)

Contact form on website
Collect name, email, company, message
Agent qualifies immediately
Show “Thank you” message

HTTP Request (Secondary)

Integrate with landing page builder
Send form data via API
Process in background
Update CRM automatically

Example:

Trigger: Form Embed
Fields: Name, Email, Company, Message
↓
Lead Qualification Agent
- Tools: Company Lookup, CRM, Lead Scoring
↓
Condition: Qualified?
- Yes → Book Meeting
- No → Add to Nurture Campaign

Content Generation

Best triggers:Schedule (Primary)

Daily at 9am
Generate social posts for the day
Post to social media
Update content calendar

HTTP Request (Secondary)

Trigger from your CMS
Generate content on-demand
Return formatted content
Publish automatically

Example:

Trigger: Schedule (Daily 9am)
↓
Content Generation Agent
- Tools: Brand Guidelines, Performance Metrics
↓
Post to Social Media APIs
↓
Update Content Calendar

Document Processing

Best triggers:Upload (Primary)

User uploads invoice/document
Flow triggers automatically
Extract data
Validate and process

Email (Secondary)

[email protected]
Email with PDF attachment
Extract and process
Send confirmation

Example:

Trigger: Upload
↓
Document Processing Agent
- Extract data (OCR if needed)
- Validate against rules
↓
Condition: Valid?
- Yes → Update ERP
- No → Human Review

External Service Integration

Best triggers:Webhook (Primary)

Stripe: payment.succeeded
GitHub: push event
Slack: message posted
Any webhook-enabled service

Example:

Trigger: Webhook
Source: Stripe payment.succeeded
↓
Process Payment Agent
- Update customer account
- Send confirmation email
- Update analytics

Scheduled Reports

Best triggers:Schedule (Primary)

Weekly on Monday 8am
Monthly on 1st at 9am
Generate report
Email to team

Example:

Trigger: Schedule (Monday 8am)
↓
Report Generation Agent
- Query database
- Analyze metrics
- Generate insights
↓
Email Report to Team

Trigger Configuration Basics

Common Settings

While each trigger type has specific settings, most triggers share these common configurations:

Trigger Name

Give your trigger a descriptive name.Good names:

“Contact Form - Homepage”
“Stripe Payment Webhook”
“Daily Sales Report Schedule”
“Invoice Upload Processor”

Bad names:

“Trigger 1”
“Test”
“My Trigger”

Clear names help you identify triggers in flows with multiple triggers.

Response Mode

How should the flow execute?Wait for Completion:

Flow completes before responding
User/caller waits for result
Best for: User-facing interactions, APIs returning data

Run in Background:

Responds immediately
Flow runs asynchronously
Best for: Long-running tasks, scheduled jobs, email processing

See individual trigger pages for specific recommendations.

Security

How to secure your trigger?Public (No Security):

Anyone with URL can trigger
Best for: Public forms, general website interactions

API Key:

Requires API key in request
Best for: Server-to-server, internal APIs
Generate key in trigger configuration

OAuth (Future):

User authentication required
Best for: User-specific actions

Availability varies by trigger type.

Rate Limiting

Prevent abuse and control costs.Set limits on:

Requests per minute
Requests per hour
Requests per day

Recommended limits:

Public endpoints: 100/hour
Internal APIs: 1,000/hour
Scheduled: Not applicable

Configure in trigger settings.

Trigger Data Flow

How Data Flows from Trigger to Steps

When a trigger fires, it passes data to the flow. This data is accessible in all subsequent steps using variable mapping. Example: Form Embed Trigger

// Data from form submission
{
  "trigger": {
    "type": "embed_form",
    "form": {
      "name": "John Smith",
      "email": "[email protected]",
      "company": "Acme Corp",
      "message": "Interested in Enterprise plan"
    },
    "timestamp": "2025-10-14T10:30:00Z"
  }
}

Accessing in Agent Step:

Prompt: ${trigger.form.message}

Agent receives: "Interested in Enterprise plan"

Accessing in HTTP Request Step:

Request Body:
{
  "name": "${trigger.form.name}",
  "email": "${trigger.form.email}",
  "source": "website_form"
}

Multiple Triggers in One Flow

Flows can have multiple triggers:

Flow: Lead Processing
├─ Trigger 1: Form Embed (Website contact form)
├─ Trigger 2: HTTP Request (Landing page API)
└─ Trigger 3: Webhook (CRM integration)

All three trigger the same flow, but with different data sources.

Use cases:

Accept leads from multiple sources
Process payments from different channels
Unified handling with varied inputs

Testing Triggers

Test Before Deploying

Always test triggers before going live:

Configure Trigger

Set up your trigger with all required settings

Save Flow

Save your flow (no need to deploy yet)

Use Test Panel

Click Test in flow builder

Simulates trigger with test data
Shows complete flow execution
Validates configuration

Test Real Trigger

For certain triggers, test the real endpoint:

Embed: Use preview URL
HTTP: Call endpoint with curl/Postman
Webhook: Use webhook testing tools
Schedule: Set near-term test time
Upload: Upload test file
Email: Send test email

Verify Results

Check that:

Flow triggered correctly
Data passed as expected
Agent processed correctly
Response returned (if applicable)

Deploy

Once testing succeeds, deploy your flow

Best Practices

Name triggers descriptively

Clear names help you manage flows with multiple triggers.✅ Good:

“Homepage Contact Form”
“Stripe Payment Success”
“Weekly Report - Mondays 8am”

❌ Bad:

“Trigger 1”
“Test”
“Form”

Secure public endpoints

If your trigger is publicly accessible:

Add rate limiting
Use CAPTCHA for forms (when available)
Monitor for abuse
Set spending alerts
Consider API keys for non-public use

Set appropriate response modes

Use “Wait for Completion” when:

Users expect immediate response
API returns data
Real-time interactions

Use “Run in Background” when:

Long-running processes (> 30 seconds)
Scheduled tasks
Email processing
No immediate response needed

Handle errors gracefully

Triggers can fail. Plan for it:

Validate input data
Set timeouts appropriately
Log failed triggers
Implement retries for critical flows
Monitor error rates

Test with realistic data

Don’t just test happy paths:

Missing fields
Invalid data
Edge cases
Malformed requests
Large payloads
Rate limit scenarios

Monitor trigger performance

Track key metrics:

Trigger count per day/week
Success vs. failure rate
Average execution time
Cost per trigger
Response times

Set alerts for anomalies.

Version your flows

When changing triggers in production:

Test thoroughly in development
Consider creating new flow version
Use phased rollout for major changes
Keep previous version active temporarily
Monitor closely after deployment

Troubleshooting Common Issues

Trigger not firing

Check:

Is flow deployed? (not just saved)
Is trigger enabled?
Are credentials correct? (for secure triggers)
Is endpoint URL correct?
Any rate limits hit?

Solutions:

Deploy the flow
Check trigger status
Verify configuration
Test with curl/Postman
Check execution logs

Data not passing to steps

Check:

Variable mapping syntax correct?
Data exists in trigger output?
Field names match exactly?
JSON structure correct?

Solutions:

Review trigger output in logs
Test variable mappings in test panel
Check for typos in field names
Use JSONPath correctly

Trigger timing out

Causes:

Flow takes too long (> 30 seconds)
Heavy processing in flow
External API delays
Large data processing

Solutions:

Use “Run in Background” mode
Optimize agent/step performance
Add timeout handling
Split into multiple flows

Rate limit errors

If hitting rate limits:

Check trigger limit settings
Review request volume
Identify source of excess traffic
Implement request queuing
Increase limits if legitimate
Add CAPTCHA if spam

Security issues

If trigger is being abused:

Add/tighten rate limits immediately
Require API key authentication
Review and block malicious IPs
Add input validation
Monitor logs for patterns
Consider moving to private endpoint

Trigger Comparison Table

Quick reference for choosing the right trigger:

Trigger Type	User-Facing	Real-Time	Security	Best For
Button Embed	✅ Yes	✅ Yes	Public/API Key	Simple actions, one-click triggers
Form Embed	✅ Yes	✅ Yes	Public/API Key	Data collection, lead capture
Chat Embed	✅ Yes	✅ Yes	Public/API Key	Conversations, support
HTTP Request	❌ No	✅ Yes	API Key	API integrations, server-to-server
Webhook	❌ No	✅ Yes	API Key/Secret	External service events
Schedule	❌ No	❌ No	N/A	Recurring tasks, reports
Upload	✅ Yes	⚠️ Depends	Public/API Key	Document processing
Email	✅ Yes	❌ No	Email address	Email automation
Stream	❌ No	✅ Yes	Internal	Real-time event processing

Next Steps

Dive deeper into specific trigger types:

Embed Triggers

Button, Form, and Chat embeds for your website

HTTP Request

Create custom API endpoints

Webhook

Receive events from external services

Schedule

Run flows on a schedule

Upload

Process uploaded documents

Email

Automate email processing

Stream Triggers

Real-time message processing (Advanced)

Flow Steps

What happens after the trigger

Need Help?

Community

Ask questions and share flows

Support

Get help from our team

Examples

Browse trigger examples

Get Started

Flows

Agents

Account Management

Advanced

​Triggers Overview

​What is a Trigger?

​Trigger Types

Embed Triggers

HTTP Request

Webhook

Schedule

Upload

Email

Stream Triggers

​Choosing the Right Trigger

​Decision Framework

How to Choose a Trigger Type

​Common Use Cases by Trigger

​Trigger Configuration Basics

​Common Settings

​Trigger Data Flow

​How Data Flows from Trigger to Steps

​Multiple Triggers in One Flow

​Testing Triggers

​Test Before Deploying

​Best Practices

​Troubleshooting Common Issues

​Trigger Comparison Table

​Next Steps

Embed Triggers

HTTP Request

Webhook

Schedule

Upload

Email

Stream Triggers

Flow Steps

​Need Help?

Community

Support

Examples

Triggers Overview

What is a Trigger?

Trigger Types

Choosing the Right Trigger

Decision Framework

Common Use Cases by Trigger

Trigger Configuration Basics

Common Settings

Trigger Data Flow

How Data Flows from Trigger to Steps

Multiple Triggers in One Flow

Testing Triggers

Test Before Deploying

Best Practices

Troubleshooting Common Issues

Trigger Comparison Table

Next Steps

Need Help?