Trigger System

The Forjinn Trigger System enables automatic workflow execution through time-based (cron) and event-driven (webhook) triggers, supporting 30+ platforms with robust scheduling capabilities.

Overview

Triggers allow you to automate workflow execution without manual intervention. They serve as entry points for workflows, automatically starting execution based on:

• Time-based schedules (cron expressions)
• External events (webhooks from various platforms)

Trigger Types

Time-Based Triggers (Cron)

Time-based triggers execute workflows on a schedule using cron expressions.

Features:

• Multiple predefined schedule types
• Custom cron expressions
• Execution limits and timeout controls
• Custom trigger messages
• UTC-based scheduling

Predefined Schedules:

• everyMinute: * * * * *
• hourly: 0 * * * *
• daily: 0 9 * * * (9 AM daily)
• weekly: 0 9 * * 1 (9 AM every Monday)
• monthly: 0 9 1 * * (9 AM on 1st of each month)

Configuration:

{
  "triggerType": "cron",
  "scheduleType": "daily",
  "cronExpression": "0 9 * * *",
  "triggerMessage": "Daily report generation",
  "maxExecutions": 100,
  "timeout": 300,
  "enabled": true
}

Event-Driven Triggers (Webhooks)

Webhook triggers respond to external events from supported platforms.

Features:

• 30+ platform integrations
• Platform-specific signature verification
• Event filtering
• Custom header validation
• Generic webhook support

Supported Platforms:

Communication & Collaboration

• Slack, Discord, Microsoft Teams
• Gmail, Outlook

Development & Project Management

• GitHub, GitLab, Jira, Trello
• Asana, Monday.com, Notion

E-commerce & Payments

• Shopify, WooCommerce
• Stripe, PayPal

Marketing & CRM

• HubSpot, Salesforce
• Mailchimp, SendGrid, Zendesk

Forms & Social

• Typeform, Google Forms, Calendly
• Facebook, Twitter/X, LinkedIn

Storage & Data

• Dropbox, Google Drive, OneDrive
• Airtable, Google Sheets

Security Implementation

Signature Verification

Each platform uses specific signature validation:

GitHub:

const signature = req.headers['x-hub-signature-256']
const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex')

Slack:

const timestamp = req.headers['x-slack-request-timestamp']
const signature = req.headers['x-slack-signature']
const baseString = `v0:${timestamp}:${payload}`
const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(baseString)
  .digest('hex')

Stripe:

const signature = req.headers['stripe-signature']
const elements = signature.split(',')
const timestamp = elements.find(e => e.startsWith('t=')).split('=')[1]
const signatures = elements.filter(e => e.startsWith('v1='))

Configuration

Node Parameters

• Trigger Type: Choose between "Cron Schedule" or "Webhook"
• Schedule Type: For cron triggers (Every Minute, Hourly, Daily, Weekly, Monthly, Custom)
• Custom Cron Expression: For custom schedules
• Webhook Platform: Select from 30+ supported platforms
• Event Types: Specify which events should trigger execution
• Webhook Secret: Secret key for signature validation
• Custom Headers: Additional security headers
• Trigger Message: Message passed to workflow
• Max Executions: Optional execution limit
• Timeout: Maximum execution time
• Notification Email: Email for notifications
• Enabled: Toggle trigger on/off

API Endpoints

• POST /api/v1/triggers - Create new trigger
• GET /api/v1/triggers - List all triggers
• GET /api/v1/triggers/:id - Get specific trigger
• PUT /api/v1/triggers/:id - Update trigger
• DELETE /api/v1/triggers/:id - Delete trigger
• POST /api/v1/triggers/webhook/:nodeId - Webhook receiver
• GET /api/v1/triggers/stats - Get trigger statistics

Working Model

Cron Trigger Flow

1. User configures time-based trigger in workflow
2. TriggerScheduler creates cron job using node-cron
3. At scheduled time, trigger executes workflow with custom message
4. Execution count tracked, limits enforced
5. Next execution time calculated and stored

Webhook Trigger Flow

1. User configures webhook trigger with platform and events
2. System generates unique webhook URL for the trigger
3. User configures webhook in external platform
4. External platform sends HTTP POST to webhook URL
5. WebhookHandler validates signature and headers
6. If valid, workflow executes with webhook payload

Best Practices

1. Security: Always use webhook secrets for external platforms
2. Testing: Test triggers in development before production
3. Monitoring: Set up proper logging and monitoring
4. Limits: Use execution limits to prevent runaway triggers
5. Error Handling: Implement proper error handling in workflows
6. Documentation: Document trigger configurations for team members

Troubleshooting

Common Issues

1. Cron not executing: Check cron expression syntax
2. Webhook validation fails: Verify secret and signature format
3. Trigger not found: Ensure trigger is enabled and properly configured
4. Execution limits reached: Check and adjust maxExecutions setting

Debug Steps

1. Check trigger status in database
2. Verify webhook URL configuration
3. Test signature validation manually
4. Review server logs for errors
5. Validate cron expression format