Triggers

Triggers enable agents to execute in response to external events via webhooks. When something happens in another system -- a form submission, a payment, a code push -- it can automatically invoke your agent.

Why Triggers?

Connect your agents to the outside world:

• Form submissions -- Process new leads instantly
• Payment events -- Handle Stripe webhooks
• CI/CD -- Run agents on deployment events
• Custom integrations -- Any system that can send HTTP requests

How Triggers Work

When an external system sends an HTTP request to your trigger's unique webhook URL, MeetLoyd validates the request, extracts and maps the input data, and executes the assigned agent or workflow with that data.

External System --> Trigger Webhook URL --> Validation & Mapping --> Agent Execution --> Response

Integration Event Registry

MeetLoyd maintains a registry of events from connected integrations. When you connect an integration, you gain access to its events.

Integration	Example Events
HubSpot	Contact Created, Deal Stage Changed, Deal Won/Lost, Ticket Created, Form Submitted
Slack	Message Posted, Bot Mentioned, Reaction Added, Channel Created
GitHub	Code Pushed, PR Opened/Merged/Closed, Issue Opened/Closed, Release Published
Stripe	Payment Succeeded/Failed, Invoice Paid, Subscription Created/Canceled

Event Categories

Events are organized by category for easier discovery: CRM, Communication, Development, Payment, Support, Calendar, HR, and Task.

Trigger Types

Type	Description
Webhook	External system sends event to MeetLoyd
Polling	MeetLoyd periodically checks for changes
WebSocket	Real-time bidirectional connection
Email	Triggers from email events
Manual	User-initiated triggers

Trigger Status

Status	Description
Active	Accepting and processing requests
Paused	Accepting but not processing (queued)
Disabled	Rejecting all requests

Creating Triggers

From the Dashboard

1. Navigate to Triggers in the sidebar
2. Click + Create Trigger
3. Name the trigger and select a target (agent or workflow)
4. Optionally enable signature verification (recommended)
5. Configure input mapping to extract fields from the webhook payload
6. Click Create

Your trigger gets a unique webhook URL that you provide to the external system.

Signature Verification

When enabled, incoming requests must include a valid HMAC-SHA256 signature in the X-Signature-256 header. The sender computes the signature using your webhook secret, and MeetLoyd verifies it before processing. This prevents unauthorized calls to your trigger.

If your secret is compromised, you can rotate it from the trigger settings. The old secret is invalidated immediately.

Always Use Signature Verification

Without signature verification, anyone with your webhook URL can invoke your agent. Enable it for all production triggers.

Input Mapping

Control how webhook data is transformed before reaching your agent:

Mapping Type	Description	Example
Template	Extract specific fields using JSONPath	Map $.pull_request.number to prNumber
Static Fields	Add constant values	Always set source: "github"
Include Headers	Pass specific HTTP headers	Include x-github-event header

You can combine all three mapping types. Only the fields you explicitly map reach the agent, which prevents sensitive data leakage and keeps input clean.

Trigger Targets

Triggers can target either an individual agent or an entire workflow:

• Agent -- The webhook payload (after mapping) becomes the agent's input
• Workflow -- The payload starts a workflow run with the mapped data as workflow input

Managing Triggers

From the dashboard, you can:

• Pause / Resume -- Temporarily stop processing without losing queued events
• Disable -- Reject all incoming requests
• Update -- Change name, mapping, or target
• Rotate Secret -- Generate a new webhook secret
• Delete -- Permanently remove the trigger

Execution History

Every trigger invocation is logged with:

• HTTP method and path
• Request and response bodies
• Execution status and duration
• Error details (if any)

Filter by status to quickly find failures and investigate issues.

Best Practices

Extract Only Needed Data

Use input mapping to pull specific fields rather than passing the entire webhook payload. This avoids sensitive data exposure and keeps agent input clean.

Add Source Identification

Include static fields like source: "stripe" and environment: "production" so your agent knows where the data came from.

Monitor Execution History

Check failed executions regularly. A spike in failures often indicates a webhook format change or authentication issue.

Use Descriptive Names

"Stripe Payment Success Handler" tells you everything. "Webhook 1" tells you nothing.

---

Next: Learn about Workflows for orchestrating multi-step processes.