> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Triggers & Webhooks
> Configure how agents start execution through integration events, schedules, webhooks, and manual triggers
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](/02-building-agents/agent-fundamentals/creating-agents/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
Navigate to agent configuration Triggers tab and click **Add Triggers**
Choose from available trigger types: integration-based (Gmail, Slack, GitHub), schedule-based (Timer), HTTP (Webhook), or manual
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
React to events in connected services (Gmail, Slack, GitHub, Drive)
Execute on time intervals using cron schedules or fixed intervals
Receive HTTP POST requests from external systems via unique URL
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.
**New Email Received**
**Use 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 or Folder Created/Updated**
**Use 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
**New Message Received**
**Use 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)
**New Pull Request, Issue, or Commit**
**Use 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:**
```
0 9 * * 1-5 → Every weekday at 9 AM
0 */6 * * * → Every 6 hours
0 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:**
**Setup:**
1. Enable API key authentication in trigger settings
2. Generate API key (shown only once - store securely)
3. External system includes key in Authorization header
**Request Example:**
```
POST /webhooks/{agent_id}/{trigger_id}
x-api-key: your-api-key-here
Content-Type: application/json
```
**How It Works:**
1. External system signs request with shared secret
2. Includes HMAC signature in request header
3. 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:**
```json theme={null}
POST /webhooks/{agent_id}/{trigger_id}
Content-Type: application/json
{
"customer_email": "user@example.com",
"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:**
```json theme={null}
{
"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:
```json theme={null}
{
"task": "Process candidate profile",
"candidateDetails": {
"fullName": "John Doe",
"email": "johndoe@example.com",
"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`:
```json theme={null}
{
"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`
```json theme={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
Define exact field types and validation rules.
**Good:**
```json theme={null}
{
"amount": "number",
"currency": "enum[USD, EUR, GBP]",
"invoice_date": "date (ISO 8601)"
}
```
**Bad:**
```json theme={null}
{
"data": "any"
}
```
Add descriptions for all input fields.
**Example:**
```json theme={null}
{
"invoice_date": {
"type": "date",
"description": "Invoice issue date in ISO 8601 format (YYYY-MM-DD)"
}
}
```
Organize related fields into objects.
**Example:**
```json theme={null}
{
"customer": {
"name": "string",
"email": "string",
"phone": "string"
}
}
```
Set defaults for optional fields.
**Example:**
```json theme={null}
{
"priority": {
"type": "enum[low, medium, high]",
"default": "medium"
}
}
```
### Testing Triggers
**Before Production:**
1. **Test Mode**: Verify trigger data structure with test inputs
2. **Validate Schema**: Ensure incoming data matches defined schema
3. **Error Scenarios**: Test with malformed data
4. **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
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.
**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
**Trigger**: New Email Received (Gmail)
**Input Schema:**
```json theme={null}
{
"subject": "string",
"body": "text",
"sender": "email",
"attachments": "array[url]"
}
```
**Workflow:**
1. Classify inquiry type
2. Extract key information
3. Check knowledge base
4. Route to team or auto-respond
5. Create support ticket
**Trigger**: New Pull Request (GitHub)
**Input Schema:**
```json theme={null}
{
"pr_number": "number",
"title": "string",
"author": "string",
"files_changed": "array[string]"
}
```
**Workflow:**
1. Analyze changed files
2. Run automated tests
3. Check security vulnerabilities
4. Validate coding standards
5. Post review comments
**Trigger**: Timer (Daily at 9 AM)
**Input Schema:**
```json theme={null}
{
"execution_timestamp": "datetime",
"report_date": "date",
"recipients": "array[email]"
}
```
**Workflow:**
1. Fetch metrics from database
2. Calculate KPIs and trends
3. Generate visualizations
4. Format report as PDF
5. Send via email
**Trigger**: Webhook (External ERP System)
**Input Schema:**
```json theme={null}
{
"invoice_id": "string",
"vendor": "string",
"amount": "number",
"pdf_url": "url"
}
```
**Workflow:**
1. Download invoice PDF
2. Extract and validate line items
3. Cross-reference with purchase orders
4. Check for duplicates
5. Route to approver
6. Update accounting system
## Next Steps
Monitor triggered agent executions and track performance
Configure human-in-the-loop workflows
Build agents that use triggers
Understand trigger data flow