> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layest.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Agent Triggers: Webhooks, Schedules & Events

> Configure triggers to start Layest agent workflows automatically. Supports webhooks, cron schedules, and event-based triggers from connected tools.

Triggers are the starting gun for your agent workflows. Instead of running an agent manually from the dashboard, you define a condition—an incoming HTTP request, a time on the clock, or an event fired by a connected tool—and Layest fires the agent automatically whenever that condition is met. This lets your agents work in the background continuously, responding to the real world without any human input required.

## Types of triggers

Layest supports three trigger types, each suited to a different automation pattern:

| Type          | Best for                                                  |
| ------------- | --------------------------------------------------------- |
| **Webhook**   | Reacting to external systems that can send HTTP requests  |
| **Scheduled** | Running agents on a fixed cadence (hourly, daily, weekly) |
| **Event**     | Responding to activity inside a connected integration     |

## Create a trigger

<Tabs>
  <Tab title="Webhook">
    A webhook trigger gives you a unique HTTPS endpoint. Any system that can send an HTTP POST request—a form, a payment processor, another platform—can start your agent by hitting that URL.

    <Steps>
      <Step title="Open the Triggers tab">
        Inside the agent editor, click the **Triggers** tab, then click **+ Add Trigger**.
      </Step>

      <Step title="Select Webhook">
        Choose **Webhook Trigger** from the trigger type list.
      </Step>

      <Step title="Configure the endpoint">
        Give the trigger a name. Layest generates a unique webhook URL for this trigger. Copy it—you'll paste it into the external system.
      </Step>

      <Step title="Set a secret (recommended)">
        Enable **Signature Verification** and copy the generated secret. Configure your external system to sign its requests with this secret so Layest can reject forged payloads.
      </Step>

      <Step title="Map payload fields">
        Under **Payload Mapping**, define which fields from the incoming JSON body should be passed to your agent as input variables.
      </Step>

      <Step title="Save and activate">
        Click **Save Trigger**. The trigger becomes active immediately—the next POST to the URL will start the agent.
      </Step>
    </Steps>

    **Example incoming payload**

    ```json theme={null}
    {
      "event": "ticket.created",
      "timestamp": "2024-11-15T09:32:00Z",
      "data": {
        "ticket_id": "TKT-8821",
        "subject": "Can't export PDF report",
        "priority": "high",
        "requester": {
          "name": "Jordan Lee",
          "email": "jordan@example.com"
        }
      }
    }
    ```

    Map `data.ticket_id`, `data.subject`, and `data.requester.email` to agent input variables so the agent has the context it needs from the first step.
  </Tab>

  <Tab title="Schedule">
    A scheduled trigger runs your agent at a fixed interval using a cron expression. Use it for recurring tasks like daily digests, weekly reports, or hourly data syncs.

    <Steps>
      <Step title="Open the Triggers tab">
        Inside the agent editor, click the **Triggers** tab, then click **+ Add Trigger**.
      </Step>

      <Step title="Select Scheduled Trigger">
        Choose **Scheduled Trigger** from the trigger type list.
      </Step>

      <Step title="Set the schedule">
        Enter a cron expression or use the visual picker to choose a preset interval. Common examples:

        | Expression    | Meaning                |
        | ------------- | ---------------------- |
        | `0 9 * * 1-5` | 9 AM every weekday     |
        | `0 * * * *`   | Every hour on the hour |
        | `0 8 * * 1`   | 8 AM every Monday      |
      </Step>

      <Step title="Set the timezone">
        Select the timezone the schedule should run in. Layest converts the cron expression to UTC internally.
      </Step>

      <Step title="Define static inputs (optional)">
        If your agent expects input variables, provide static values or reference a data source under **Trigger Inputs**. These are passed to the agent each time it runs.
      </Step>

      <Step title="Save and activate">
        Click **Save Trigger**. The agent will run automatically at the next scheduled time.
      </Step>
    </Steps>

    <Info>
      You can pause a scheduled trigger without deleting it. Click the toggle next to the trigger name in the Triggers tab to suspend and resume the schedule.
    </Info>
  </Tab>

  <Tab title="Event">
    An event trigger listens for specific activity inside a connected integration and fires your agent the moment that activity occurs—for example, when a new support ticket is created or when a contact is updated in your CRM.

    <Steps>
      <Step title="Connect the integration">
        Before creating an event trigger, make sure the relevant integration is connected and attached to this agent. See [Integrations](/capabilities/integrations) for setup instructions.
      </Step>

      <Step title="Open the Triggers tab">
        Inside the agent editor, click the **Triggers** tab, then click **+ Add Trigger**.
      </Step>

      <Step title="Select Event Trigger">
        Choose **Event Trigger** from the trigger type list.
      </Step>

      <Step title="Pick the integration and event">
        Select the connected integration from the dropdown, then choose the specific event to listen for (for example, *New Email Received* or *New Jira Issue Created*).
      </Step>

      <Step title="Add filters (optional)">
        Narrow which events fire the agent using filter conditions. For example, only trigger when `priority = high` or when the email sender domain matches `@example.com`.
      </Step>

      <Step title="Map event data to agent inputs">
        Specify which fields from the event payload map to your agent's input variables, then click **Save Trigger**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Configure conditions and filters

Every trigger type supports an optional **Conditions** block. Conditions let you gate the agent run on properties of the incoming data without writing any code.

* **Field** – The payload or event field to inspect (for example, `data.priority`).
* **Operator** – Comparison to apply: `equals`, `not equals`, `contains`, `greater than`, etc.
* **Value** – The value to compare against.

Add multiple conditions and choose whether **all** must be true (AND) or **any** must be true (OR) before the agent fires.

## Test a trigger from the dashboard

You don't need to wait for a real external event to verify a trigger is wired up correctly.

<Steps>
  <Step title="Open the trigger detail">
    In the **Triggers** tab, click the trigger you want to test.
  </Step>

  <Step title="Click Send Test Event">
    Click **Send Test Event**. For webhook and event triggers, Layest presents an editable JSON editor pre-filled with a sample payload matching the expected schema.
  </Step>

  <Step title="Edit the payload if needed">
    Adjust any field values to represent the scenario you want to test, then click **Run Test**.
  </Step>

  <Step title="Review the run">
    Layest fires the agent with the test payload and opens the run trace automatically. Inspect each step to confirm inputs were mapped correctly and the agent behaved as expected.
  </Step>
</Steps>

<Note>
  Test runs are marked as `test` in the run history and do not count against any usage quotas tied to live triggers.
</Note>