# Agent Triggers

> **=� Complete Trigger Configuration Guide**
>
> Configure automated triggers to activate your agents based on external events like webhooks.

## = **What Are Agent Triggers?**

Agent Triggers enable your agents to respond automatically to external events without manual intervention. When a trigger is activated, it sends a message to your agent, which then processes the request and optionally returns a response.

**Key Benefits:**

* **Automated Activation**: Agents respond to events in real-time
* **Webhook Integration**: Connect external systems via HTTP webhooks
* **Thread Management**: Continue existing conversations or start new ones
* **Secure Authentication**: Support for multiple auth methods
* **Event Logging**: Track all trigger activations and their outcomes

***

## <� **Trigger Types**

### **Webhook Triggers**

Webhook triggers allow external systems to activate your agent by sending HTTP requests to a unique URL.

**How It Works:**

1. Create a webhook trigger for your agent
2. Configure the HTTP method, authentication, and response code
3. Share the webhook URL with your external system
4. When the webhook receives a request, it sends a message to your agent
5. The agent processes the request and optionally returns a response

***

## � **Webhook Configuration**

### **HTTP Method**

Choose which HTTP method the webhook should accept:

| Method     | Best For                                        |
| ---------- | ----------------------------------------------- |
| **POST**   | Sending data to create or process (recommended) |
| **GET**    | Simple queries or status checks                 |
| **PUT**    | Updating existing resources                     |
| **DELETE** | Removing or canceling operations                |

**Default**: POST

### **Authentication**

Protect your webhook endpoint from unauthorized access:

#### **None**

* No authentication required
* � **Use only for public endpoints or testing**

#### **Basic Authentication**

* Username and password protection
* Header format: `Authorization: Basic <username>:<password>`
* **Best for**: Internal systems with simple auth requirements

**Configuration:**

* **Username**: The required username for authentication
* **Password**: The required password for authentication

#### **Bearer Token**

* Token-based authentication
* Header format: `Authorization: Bearer <token>`
* **Best for**: API integrations with token-based security

**Configuration:**

* **Token**: The secret token that must be provided in the request

### **Response Code**

Configure the HTTP status code returned by the webhook:

| Code    | Meaning               | Use Case                            |
| ------- | --------------------- | ----------------------------------- |
| **200** | OK                    | Standard success response (default) |
| **201** | Created               | Resource creation confirmation      |
| **202** | Accepted              | Request accepted for processing     |
| **204** | No Content            | Success with no response body       |
| **301** | Moved Permanently     | Permanent redirect                  |
| **302** | Found                 | Temporary redirect                  |
| **304** | Not Modified          | Cached response                     |
| **400** | Bad Request           | Client error response               |
| **401** | Unauthorized          | Authentication required             |
| **403** | Forbidden             | Access denied                       |
| **404** | Not Found             | Resource not found                  |
| **500** | Internal Server Error | Server error                        |

**Default**: 200

***

## =� **Task Configuration**

Task configuration determines what happens when the trigger is activated.

### **Task Type: Send Message to Chat**

The trigger sends a message to your agent, optionally within a specific conversation thread.

#### **Message Template**

Define the message content sent to your agent. You can use template variables to include data from the webhook request:

**Available Variables:**

* `{{event.body}}` - The request body data
* `{{event.headers}}` - The request headers
* `{{event.method}}` - The HTTP method (GET, POST, PUT, DELETE)
* `{{event.url}}` - The request URL

**Examples:**

```
New support request: {{event.body}}
```

```
User {{event.body.name}} submitted a form with email {{event.body.email}}
```

```
Webhook received from {{event.headers.user-agent}} via {{event.method}} request
```

**Constraints:**

* Minimum length: 1 character
* Maximum length: 10,000 characters

#### **Chat ID (Optional)**

Specify whether to continue an existing conversation or start a new one:

* **Not provided**: Creates a new conversation thread each time the trigger fires
* **Provided**: Sends the message to an existing thread

**Using Dynamic Chat IDs:**

You can extract the chat ID from the webhook request:

```
{{event.body.thread_id}}
```

```
{{event.body.conversation_id}}
```

**Requirements:**

* Must be a valid UUID format
* Thread must exist and belong to the same agent
* If invalid, the trigger will fail with an error

***

## = **Trigger Lifecycle**

### **Creating a Trigger**

1. Navigate to your agent's configuration
2. Open the **Triggers** tab
3. Click **Create New Trigger**
4. Configure:
   * **Name**: Descriptive identifier for the trigger
   * **Description**: Optional details about the trigger's purpose
   * **Trigger Type**: Select "Webhook"
   * **Webhook Settings**: Method, authentication, response code
   * **Task Settings**: Message template and optional chat ID
5. Save to generate the webhook URL

### **Webhook URL**

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

```
https://api.agenticflow.com/webhooks/{unique-path-id}
```

* The `{unique-path-id}` is a UUID automatically generated for security
* Share this URL only with authorized systems
* The URL remains the same unless you delete and recreate the trigger

### **Activating/Deactivating**

* **Active**: The trigger responds to incoming requests
* **Inactive**: The trigger ignores all requests (returns 404)
* Toggle the status anytime without deleting the trigger

### **Updating a Trigger**

You can modify:

*  Name and description
*  Authentication settings
*  HTTP method
*  Response code
*  Message template
*  Chat ID configuration
*  Active/inactive status

**Note**: The webhook URL/path cannot be changed after creation.

### **Deleting a Trigger**

* Permanently removes the trigger
* The webhook URL becomes invalid immediately
* All event history is retained for audit purposes

***

## =� **Event Monitoring**

### **Trigger Events**

Every time your webhook is called, an event is recorded with:

* **Event ID**: Unique identifier for the trigger activation
* **Timestamp**: When the webhook was called
* **Request Details**:
  * HTTP method
  * Request headers
  * Request body
  * Request URL
* **Response Details**:
  * Response status code
  * Response headers
  * Response body
* **Status**: `success` or `failed`
* **Error**: Error message if the trigger failed

### **Viewing Events**

Access event history through:

* The Triggers tab in your agent configuration
* Filter by specific trigger or view all events
* Paginate through historical events

### **Event Retention**

All trigger events are stored for auditing and troubleshooting purposes.

***

## =� **Security Best Practices**

1. **Always Use Authentication**
   * Avoid "None" auth for production webhooks
   * Use Bearer tokens for API integrations
   * Use Basic auth for simple internal systems
2. **Protect Your Webhook URL**
   * Treat the webhook URL as a secret
   * Don't expose it in public repositories or documentation
   * Rotate tokens periodically by updating the trigger
3. **Validate Request Data**
   * Design your agent prompts to handle unexpected data
   * Use structured message templates to sanitize inputs
4. **Monitor Event Logs**
   * Regularly review trigger events for suspicious activity
   * Set up alerts for failed authentications
   * Investigate unexpected usage patterns
5. **Use HTTPS**
   * All webhook URLs use HTTPS by default
   * Never downgrade to HTTP for production use

***

## =� **Use Cases**

### **Customer Support Integration**

Trigger your support agent when customers submit tickets:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 202 (Accepted)

**Message Template:**

```
New support ticket from {{event.body.customer_email}}:
Subject: {{event.body.subject}}
Message: {{event.body.message}}
Priority: {{event.body.priority}}
```

### **Form Processing**

Process form submissions automatically:

**Webhook Config:**

* Method: POST
* Auth: Basic
* Response: 200 (OK)

**Message Template:**

```
Process this form submission:
{{event.body}}
```

### **Multi-System Integration**

Continue conversations across different systems:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 200
* Chat ID: `{{event.body.session_id}}`

**Message Template:**

```
{{event.body.user_message}}
```

### **Notification Processing**

Handle incoming notifications from external services:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 204 (No Content)

**Message Template:**

```
Alert received: {{event.body.alert_type}}
Details: {{event.body.details}}
Action required: {{event.body.action}}
```

***

## � **Common Issues**

### **Trigger Returns 404**

**Possible Causes:**

* Trigger is set to inactive
* Webhook URL is incorrect
* Trigger has been deleted

**Solution:**

* Verify the trigger is active
* Check the webhook URL matches exactly
* Confirm the trigger still exists

### **Authentication Failures (401)**

**Possible Causes:**

* Incorrect username/password (Basic auth)
* Invalid or expired token (Bearer auth)
* Missing Authorization header

**Solution:**

* Verify credentials match the trigger configuration
* Check the Authorization header format
* Ensure the token hasn't been rotated

### **Method Not Allowed (405)**

**Possible Cause:**

* Request method doesn't match trigger configuration

**Solution:**

* Verify you're using the correct HTTP method (GET, POST, PUT, DELETE)

### **Invalid Thread ID (400)**

**Possible Causes:**

* Chat ID template returns invalid UUID
* Referenced thread doesn't exist
* Thread belongs to different agent

**Solution:**

* Validate the chat ID format is a valid UUID
* Ensure the thread exists before triggering
* Verify thread ownership

***

## =� **Quick Reference**

### **Supported HTTP Methods**

GET, POST, PUT, DELETE

### **Authentication Types**

None, Basic, Bearer Token

### **Response Codes**

200, 201, 202, 204, 301, 302, 304, 400, 401, 403, 404, 500

### **Template Variables**

* `{{event.body}}` - Request body
* `{{event.body.field}}` - Specific body field
* `{{event.headers}}` - All headers
* `{{event.method}}` - HTTP method
* `{{event.url}}` - Request URL

### **Message Constraints**

* Min length: 1 character
* Max length: 10,000 characters

***

## = **Related Documentation**

* [**MCP Tools Integration**](https://docs.agenticflow.ai/ai-agents/mcp-tools) - Connect external tools to your agents
* [**Tasks & Multi-Step Workflows**](https://docs.agenticflow.ai/ai-agents/broken-reference) - Configure complex agent workflows
* [**API Documentation**](https://docs.agenticflow.ai/ai-agents/broken-reference) - Programmatic trigger management

***

**Need Help?** Visit the [Support & Troubleshooting](https://docs.agenticflow.ai/support/12-support) section or check the [FAQ](https://github.com/PixelML/agenticflow-docs/blob/main/docs/12-support/faq.md).