Workflow Triggers

Triggers define how and when your workflows start. Each workflow can have multiple triggers, allowing the same workflow to be started in different ways.

Trigger Types

AffinityBots supports five trigger types:

Type	Starts When	Best For
Manual	User clicks button or calls API	Testing, on-demand tasks
Webhook	External system sends HTTP request	Integrations, real-time events
Schedule	Cron schedule fires	Recurring tasks, reports
Form	User submits input form	Collecting structured data
Integration	Connected app event	Native integrations (coming soon)

---

Manual Trigger

The simplest trigger—start workflows on demand.

Configuration

Setting	Description
Name	Display name (e.g., "Run Manually")
Description	Optional description

How to Use

Via UI:

1. Open the workflow
2. Click "Run" button
3. Enter input (if required)
4. Click "Execute"

Via API:

curl -X POST https://affinitybots.com/api/workflows/{workflow_id}/triggers/{trigger_id}/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Your input message here"}'

Via MCP:

affinitybots_execute_workflow(workflow_id, input, trigger_id)

---

Webhook Trigger

Receive data from external systems via HTTP POST requests.

Configuration

Setting	Description
Name	Display name (e.g., "GitHub PR Webhook")
Description	What this webhook receives

Webhook URL

After creating the trigger, you'll receive a unique webhook URL:

https://affinitybots.com/api/workflows/{workflow_id}/triggers/{trigger_id}/invoke

Sending Data

External systems send JSON data via POST:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "pull_request",
    "action": "opened",
    "title": "Add new feature",
    "body": "This PR adds..."
  }'

The entire JSON payload is passed to your workflow as input.

Security

• Each webhook URL is unique and unguessable
• Consider adding webhook signature verification for sensitive workflows
• Revoke and regenerate webhook URLs if compromised

Common Integrations

Service	Event	Use Case
GitHub	Push/PR events	Code review automation
Stripe	Payment events	Order processing
Zapier	Any trigger	Connect 5000+ apps
Custom API	Any event	Internal systems

---

Schedule Trigger

Run workflows automatically on a recurring schedule using cron expressions.

Configuration

Setting	Description
Name	Display name (e.g., "Daily Report")
Schedule	Cron expression
Timezone	Timezone for schedule (default: UTC)
Input	Default input for scheduled runs

Cron Expression Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common Schedules

Schedule	Cron Expression	Description
Every hour	0 * * * *	At minute 0 of every hour
Every day at 9am	0 9 * * *	9:00 AM daily
Every Monday	0 9 * * 1	9:00 AM every Monday
Every month	0 0 1 * *	Midnight on the 1st
Every 15 minutes	*/15 * * * *	Every 15 minutes

Example: Daily Summary Report

Schedule: 0 8 * * 1-5   (8 AM, Monday-Friday)
Input: "Generate daily summary of yesterday's activities"

[!NOTE] Scheduled workflows use a background worker. Ensure the schedule worker is running in production.

---

Form Trigger

Collect structured user input before starting the workflow.

Configuration

Setting	Description
Name	Display name (e.g., "Content Brief Form")
Description	Instructions for users
Fields	Form field definitions

Field Types

Type	Description	Example
Text	Single line input	Name, title
Textarea	Multi-line input	Description, content
Select	Dropdown options	Category, priority
Number	Numeric input	Budget, quantity
Email	Email address	Contact email
URL	Web URL	Source link

Form Configuration Example

{
  "fields": [
    {
      "name": "topic",
      "type": "text",
      "label": "Blog Topic",
      "required": true,
      "placeholder": "Enter the topic..."
    },
    {
      "name": "tone",
      "type": "select",
      "label": "Writing Tone",
      "options": ["Professional", "Casual", "Technical"],
      "required": true
    },
    {
      "name": "notes",
      "type": "textarea",
      "label": "Additional Notes",
      "required": false
    }
  ]
}

Using Form Data

Form submissions are passed to your workflow as structured JSON:

{
  "topic": "AI in Healthcare",
  "tone": "Professional",
  "notes": "Focus on recent developments..."
}

Your first task's agent receives this as input.

---

Integration Trigger (Coming Soon)

Start workflows from events in connected applications.

Planned Integrations

Integration	Events
HubSpot	New contact, deal stage change
GitHub	New PR, issue created
Slack	Message received, reaction added
Gmail	New email matching filter

---

Managing Triggers

Adding Triggers

1. Open workflow in the builder
2. Click "Add Trigger" in the toolbar or on the canvas
3. Select trigger type
4. Configure settings
5. Save

Editing Triggers

1. Click on the trigger node in the canvas
2. Update configuration in the side panel
3. Changes auto-save

Deleting Triggers

1. Select the trigger node
2. Press Delete key or click the trash icon
3. Confirm deletion

[!WARNING] Deleting a webhook trigger invalidates its URL immediately. Any systems using that URL will receive errors.

Multiple Triggers

A single workflow can have multiple triggers:

[Manual Trigger]──────┐
[Webhook Trigger]─────┼───→ [Workflow Tasks]
[Schedule Trigger]────┘

This allows:

• Manual testing with manual trigger
• Real-time execution via webhook
• Scheduled batch runs

Best Practices

1. Start with Manual: Always have a manual trigger for testing
2. Name Clearly: Use descriptive names for each trigger
3. Document Webhooks: Keep track of which systems use which webhook URLs
4. Test Schedules: Verify cron expressions with a cron parser before deploying
5. Validate Forms: Use required fields for critical data

Troubleshooting

Schedule not firing

• Verify the schedule worker is running
• Check the cron expression syntax
• Confirm timezone settings

Webhook not receiving data

• Verify the webhook URL is correct
• Check that the source system is sending JSON
• Review any firewall or network issues

Form validation errors

• Ensure required fields have values
• Check field type constraints
• Verify JSON payload format

Next Steps

• Creating a Workflow - Build your workflow
• Adding Guardrails - Validate workflow outputs
• Introduction to Workflows - Workflow concepts