# 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**](/ai-agents/mcp-tools.md) - Connect external tools to your agents
* [**Tasks & Multi-Step Workflows**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/03-agents/configuration/tasks.md) - Configure complex agent workflows
* [**API Documentation**](/developers/api.md) - Programmatic trigger management

***

**Need Help?** Visit the [Support & Troubleshooting](/support/12-support.md) section.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agenticflow.ai/ai-agents/trigger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.