Triggers & Webhooks

Triggers define how your agent receives data and when it executes. They determine what starts your agent’s workflow and what data becomes available to all nodes as task_query.

From Building Agents: Triggers are configured during agent setup. This page covers detailed configuration and webhook implementation for production deployments. See Creating Agents for initial setup.

Understanding Triggers

Every trigger serves two functions: Execution Initiation - Determines when the workflow starts (event occurs, schedule fires, HTTP request received, or manual execution) Data Provisioning - Defines input schema that becomes task_query variable accessible to all workflow nodes

Adding Triggers

Click Add Triggers

Navigate to agent configuration Triggers tab and click Add Triggers

Select Trigger Type

Choose from available trigger types: integration-based (Gmail, Slack, GitHub), schedule-based (Timer), HTTP (Webhook), or manual

Configure Trigger

Define trigger-specific settings based on selected type. Configuration varies by trigger.Example: Gmail Trigger Configuration

Set connection, trigger context, and filters (attachments, reply behavior, body content matching).Example: Timer Trigger Configuration

Set schedule (time zone, start time, recurrence) and optional prompt for context.

Trigger Types

Integration-Based

React to events in connected services (Gmail, Slack, GitHub, Drive)

Schedule-Based

Execute on time intervals using cron schedules or fixed intervals

HTTP-Based (Webhooks)

Receive HTTP POST requests from external systems via unique URL

Manual

User-initiated execution for on-demand processing and testing

Integration-Based Triggers

Event-driven triggers respond to actions in connected services, enabling real-time automation.

Email Triggers (Gmail, Outlook)

New Email ReceivedUse Cases:

Email triage and classification
Data extraction from messages
Auto-categorization and routing
Automated responses

Input Data:

Subject, body, sender, attachments
Timestamp, thread context
Labels and metadata

Configuration:

Connect Gmail or Outlook integration
Define folder/label filters (optional)
Set input schema for email data

File System Triggers (Google Drive, Dropbox, SharePoint)

File or Folder Created/UpdatedUse Cases:

Document processing pipelines
Data synchronization
Team notifications
Content validation

Input Data:

File name, path, content
Modification details
File metadata

Configuration:

Connect Drive/Dropbox/SharePoint
Specify watched folders
Define file type filters

Communication Triggers (Slack, Microsoft Teams)

New Message ReceivedUse Cases:

Action item extraction
Automated responses
Conversation monitoring
Workflow initiation from chat

Input Data:

Message content, channel
Sender, timestamp
Thread context

Configuration:

Connect Slack or Teams
Specify channels to monitor
Set message filters (keywords, mentions)

Development Triggers (GitHub, GitLab)

New Pull Request, Issue, or CommitUse Cases:

Code review automation
CI/CD integration
Automated testing
Deployment workflows

Input Data:

PR/Issue details
Files changed, author
Branch, description

Configuration:

Connect GitHub or GitLab
Specify repositories
Define event filters

Schedule-Based Triggers

Execute agents on defined time intervals for recurring automation. Timer Trigger Run agents automatically based on time schedules: Schedule Types:

Interval-Based: Every X minutes/hours/days
Cron-Based: Specific times with cron syntax
Business Hours: Monday-Friday during work hours

Common Use Cases:

Daily reports generated at 9 AM
Database synchronization every 6 hours
Weekly maintenance tasks
System monitoring checks every 15 minutes

Cron Schedule Examples:

9 * * 1-5    → Every weekday at 9 AM
*/6 * * *    → Every 6 hours
0 * * 0      → Every Sunday at midnight

Input Data:

Timestamp of scheduled execution
Schedule metadata (frequency, next run time)
Optional: Date range or execution count

HTTP-Based Triggers (Webhooks)

Receive HTTP requests from external systems to trigger agent execution programmatically. Webhook Configuration Beam provides a unique webhook URL endpoint for each agent. External systems send HTTP POST requests to this URL. Webhook URL Format:

https://api.beamstudio.ai/webhooks/{agent_id}/{trigger_id}

Request Requirements:

Method: POST (required)
Content-Type: application/json
Body: JSON payload matching defined input schema
Headers: Optional authentication

Authentication Options:

API Key Authentication

Setup:

Enable API key authentication in trigger settings
Generate API key (shown only once - store securely)
External system includes key in Authorization header

Request Example:

POST /webhooks/{agent_id}/{trigger_id}
Authorization: Bearer your-api-key-here
Content-Type: application/json

Signature Validation

How It Works:

External system signs request with shared secret
Includes HMAC signature in request header
Beam validates signature before executing agent

Request Example:

POST /webhooks/{agent_id}/{trigger_id}
X-Signature: sha256=calculated_signature
Content-Type: application/json

Webhook Payload Structure

Input Data Access

The HTTP request body becomes the task_query variable available to all workflow nodes. Example Request:

POST /webhooks/{agent_id}/{trigger_id}
Content-Type: application/json

{
  "customer_email": "[email protected]",
  "invoice_number": "INV-2025-001",
  "amount": 1500.00,
  "attachments": ["https://storage.example.com/invoice.pdf"]
}

Node Access:

task_query.customer_email
task_query.invoice_number
task_query.amount
task_query.attachments

Core Payload Structure

Beam processes JSON payloads and dynamically interprets keys and values. Basic Payload:

{
  "task": "Process customer inquiry",
  "parsingUrls": [
    "https://example.com/customer-data"
  ],
  "encodedContextFiles": [
    {
      "mimeType": "application/pdf",
      "fileType": "document",
      "fileExtension": "pdf",
      "data": "BASE64_ENCODED_CONTENT",
      "fileName": "invoice.pdf",
      "fileSize": "2 MB"
    }
  ],
  "metadata": {
    "clientId": "CLIENT_123",
    "sourceSystem": "CRM",
    "timestamp": "2025-11-09T22:00:00Z"
  }
}

Structured Data

Beam supports nested objects and arrays for complex data:

{
  "task": "Process candidate profile",
  "candidateDetails": {
    "fullName": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "experience": [
      {
        "company": "Company A",
        "jobTitle": "Software Engineer",
        "duration": {
          "from": "2018-06-01",
          "to": "2022-05-31"
        }
      }
    ]
  }
}

File Attachments

Files must be Base64-encoded and included under encodedContextFiles:

{
  "task": "Upload candidate resume",
  "encodedContextFiles": [
    {
      "mimeType": "application/pdf",
      "fileType": "document",
      "fileExtension": "pdf",
      "data": "BASE64_ENCODED_FILE_CONTENT",
      "fileName": "resume.pdf",
      "fileSize": "2 MB"
    }
  ]
}

Beam stores files for future reference and extracts information for workflow use.

Data Format Best Practices

Timestamps: ISO 8601 format YYYY-MM-DDTHH:mm:ssZ Currency: { "amount": 1000, "currency": "USD" } Boolean values: true or false Unique Identifiers: String format "clientId": "123456" Missing/Null Values: Omit field or set to null

{
  "jobTitle": "Software Engineer",
  "salary": null,
  "location": "Remote"
}

Manual Triggers

User-initiated execution for on-demand processing and testing. When to Use:

Ad-hoc processing tasks
Testing workflow changes
Debug mode execution
User-requested operations

Input Methods:

Form-based input (define fields in trigger config)
File upload for document processing
Re-run previous task with same inputs
Custom JSON input for testing

Configuration Best Practices

Input Schema Design

Be Specific with Types

Define exact field types and validation rules.Good:

{
  "amount": "number",
  "currency": "enum[USD, EUR, GBP]",
  "invoice_date": "date (ISO 8601)"
}

Bad:

{
  "data": "any"
}

Document Every Field

Add descriptions for all input fields.Example:

{
  "invoice_date": {
    "type": "date",
    "description": "Invoice issue date in ISO 8601 format (YYYY-MM-DD)"
  }
}

Use Nested Objects

Organize related fields into objects.Example:

{
  "customer": {
    "name": "string",
    "email": "string",
    "phone": "string"
  }
}

Provide Default Values

Set defaults for optional fields.Example:

{
  "priority": {
    "type": "enum[low, medium, high]",
    "default": "medium"
  }
}

Testing Triggers

Before Production:

Test Mode: Verify trigger data structure with test inputs
Validate Schema: Ensure incoming data matches defined schema
Error Scenarios: Test with malformed data
Authentication: Verify security measures work correctly

Integration Trigger Testing:

Create test events in connected services
Verify agent receives correct data
Check timestamp and metadata accuracy

Webhook Trigger Testing:

Use Postman or cURL to send test requests
Verify authentication requirements
Test various payload structures
Confirm error responses for invalid requests

Multiple Triggers

Add multiple triggers to the same agent for different entry points.Example: Customer Support Agent

Trigger 1: Email - Customer emails support inbox
Trigger 2: Webhook - Integration with ticketing system
Trigger 3: Manual - Ad-hoc inquiry handling

All three execute the same workflow with different data sources.

Security Checklist

Webhook Security:

Enable API key authentication for production
Use signature validation for sensitive operations
Whitelist IP addresses if source is known
Monitor webhook execution logs
Rotate API keys quarterly
Validate all input data before processing

Integration Security:

Grant minimum required permissions
Use service accounts instead of personal accounts
Review and revoke unused connections
Monitor integration access logs

Example Use Cases

Customer Support Automation

Trigger: New Email Received (Gmail)Input Schema:

{
  "subject": "string",
  "body": "text",
  "sender": "email",
  "attachments": "array[url]"
}

Workflow:

Classify inquiry type
Extract key information
Check knowledge base
Route to team or auto-respond
Create support ticket

Code Review Automation

Trigger: New Pull Request (GitHub)Input Schema:

{
  "pr_number": "number",
  "title": "string",
  "author": "string",
  "files_changed": "array[string]"
}

Workflow:

Analyze changed files
Run automated tests
Check security vulnerabilities
Validate coding standards
Post review comments

Daily Report Generation

Trigger: Timer (Daily at 9 AM)Input Schema:

{
  "execution_timestamp": "datetime",
  "report_date": "date",
  "recipients": "array[email]"
}

Workflow:

Fetch metrics from database
Calculate KPIs and trends
Generate visualizations
Format report as PDF
Send via email

Invoice Processing via Webhook

Trigger: Webhook (External ERP System)Input Schema:

{
  "invoice_id": "string",
  "vendor": "string",
  "amount": "number",
  "pdf_url": "url"
}

Workflow:

Download invoice PDF
Extract and validate line items
Cross-reference with purchase orders
Check for duplicates
Route to approver
Update accounting system

Next Steps

Task Executions

Monitor triggered agent executions and track performance

Automation Modes

Configure human-in-the-loop workflows

Creating Agents

Build agents that use triggers

Variables & State

Understand trigger data flow

Getting Started

Building Agents

Running & Operations

Observability & Analytics

Resources

Understanding Triggers

Adding Triggers

Trigger Types

Integration-Based

Schedule-Based

HTTP-Based (Webhooks)

Manual

Integration-Based Triggers

Schedule-Based Triggers

HTTP-Based Triggers (Webhooks)

Webhook Payload Structure

Input Data Access

Core Payload Structure

Structured Data

File Attachments

Data Format Best Practices

Manual Triggers

Configuration Best Practices

Input Schema Design

Testing Triggers

Example Use Cases

Next Steps

Task Executions

Automation Modes

Creating Agents

Variables & State

Getting Started

Building Agents

Running & Operations

Observability & Analytics

Resources

​Understanding Triggers

​Adding Triggers

​Trigger Types

Integration-Based

Schedule-Based

HTTP-Based (Webhooks)

Manual

​Integration-Based Triggers

​Schedule-Based Triggers

​HTTP-Based Triggers (Webhooks)

​Webhook Payload Structure

​Input Data Access

​Core Payload Structure

​Structured Data

​File Attachments

​Data Format Best Practices

​Manual Triggers

​Configuration Best Practices

​Input Schema Design

​Testing Triggers

​Example Use Cases

​Next Steps

Task Executions

Automation Modes

Creating Agents

Variables & State

Understanding Triggers

Adding Triggers

Trigger Types

Integration-Based Triggers

Schedule-Based Triggers

HTTP-Based Triggers (Webhooks)

Webhook Payload Structure

Input Data Access

Core Payload Structure

Structured Data

File Attachments

Data Format Best Practices

Manual Triggers

Configuration Best Practices

Input Schema Design

Testing Triggers

Example Use Cases

Next Steps