HomeCommunityDiscordLogin

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

Need Help? Visit the Support & Troubleshooting section or check the FAQ.

PreviousTask ManagementNextAgent Templates

Last updated

Was this helpful?