---
title: Workflow agent triggers
slug: agent-platform/docs/workflow-agent-triggers
docTags: 
createdAt: 2026-08-12T15:37:04.000Z
---

Triggers control when workflow agents in Agent Platform run. Workflow triggers start a [workflow agent](docId:2HD0fUsIsfdek516VtN9l) when their defined conditions are met. Each trigger listens for a specific event, such as a chat command, a scheduled time, a webhook call, or an email. When that event occurs, the workflow agent runs.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Kv0bpbYqtsU0uVE8sJdZp_intro.png)

| **Trigger**                                | **Best for**                                 | **Example**                                                     |
| ------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------- |
| [Chat Input](docId\:pYeMYR_1QCBBfc6rGEwlR) | On-demand runs from Mark chat.               | Type `@workflow generate weekly brief` to kick off automation.  |
| [Scheduler](docId\:pYeMYR_1QCBBfc6rGEwlR)  | Time-based and recurring tasks.              | Nightly sync at 10:00 PM.                                       |
| [Webhook](docId\:pYeMYR_1QCBBfc6rGEwlR)    | Immediate reactions to external events.      | Trigger on incoming webhook or when a build pipeline completes. |
| [Email](docId\:pYeMYR_1QCBBfc6rGEwlR)      | Human approvals and attachment-driven flows. | Reviewer emails approval or sends a CSV to process.             |

## Trigger limitations and considerations

### Connections

When configuring a trigger for your workflow agent, the trigger establishes a connection to a specific associated Optimizely instance during its creation.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/-cbtKd_1m7zVv6BLhS9vG_product-connections-multiple.png)

If you change the connection *after* creating a trigger, the trigger may continue to reference the original instance. This can lead to unexpected behavior or issues where the workflow agent does not interact with the intended instance.

To prevent this, ensure that your connections to all associated instances are established before creating workflow triggers. If you must change a connection, recreate any affected triggers to ensure they are correctly linked to the updated instance.

See the [Connections](docId\:pe0pbUJveWrG8ewvZWDRE) section in the[Get started with Mark for administrators](docId\:pe0pbUJveWrG8ewvZWDRE) documentation.

### Creator

A workflow agent's actions display as performed by the user who created the trigger. For example, if User1 creates a trigger and the workflow agent creates a page in Optimizely Content Management System (SaaS), User1 displays as the page's creator.

### Field importance for AI

Descriptions and other configuration fields play an important role in how Mark processes workflow agents. All description fields contribute to clarity, maintainability, and future functionality. Required fields are meaningful either immediately or for upcoming platform capabilities. Because of this, enter complete and accurate descriptions for all fields, including those in specialized agents and tools.

## Trigger priority

Trigger priority lets you control which workflow agent runs execute first when your Mark instance reaches its concurrency limit. The concurrency limit is the fixed number of workflow agent runs that an instance executes at the same time. Set a priority on each trigger so that user-facing workflow agents run without delay and automated, high-volume workflow agents wait for capacity.

Each trigger has a **Priority** setting with two options:

- **Standard** – The run takes precedence when slots are limited. Use it for workflow agents where someone waits for a response.
- **Background** – The run yields to standard runs when slots are limited. Use it for automated or batch workflow agents where a short delay is acceptable.

### Why trigger priority matters

Workflow agents share a fixed number of execution slots per instance. Without priority, every run competes equally for those slots. For example, a scheduled workflow agent starts dozens of runs at midnight. Those runs block a teammate who starts a workflow agent from Mark chat the next morning, even though the chat interaction needs an immediate response.

When a background run reaches a slot while a standard run waits, the background run releases the slot and reschedules. Interactive workflow agents always get first access to execution capacity.

### Default priority by trigger type

Each trigger type has a default priority that matches its typical use. Change the priority on any trigger at any time.

| **Trigger** | **Default priority** | **Reason**                                       |
| ----------- | -------------------- | ------------------------------------------------ |
| Chat        | Standard             | Someone starts the run and waits for a response. |
| Scheduler   | Background           | Runs automatically on a recurring cadence.       |
| Webhook     | Background           | Runs automatically and often in high volume.     |
| Email       | Background           | Processes incoming email automatically.          |

### Trigger priority examples

Priority matters most when an interactive workflow agent and an automated one share the same instance. The following examples demonstrate how the default priorities keep interactive runs responsive during heavy automated activity.

- A content team generates SEO metadata on demand with a chat trigger. A separate scheduled workflow agent audits broken links every 30 minutes. Keep the audit at **Background** so it yields whenever someone requests metadata.
- A webhook trigger ingests product feed updates and can receive hundreds of events at once. Merchandisers ask inventory questions through a chat trigger. Keep the webhook trigger at **Background** so feed processing never blocks merchandiser queries.

### How Mark schedules runs by priority

When a run starts, Mark assigns it an execution class based on the trigger's priority. The execution class determines how the run behaves at each concurrency gate, which is a point where Mark checks for an available slot.

1. The run reaches a concurrency gate at workflow start, before a step executes, or after a step completes.
2. A standard run proceeds into the next available slot.
3. For a background run, Mark checks whether any standard runs wait for a slot on the same instance.
4. If a standard run waits, the background run releases its slot and reschedules.
5. If no standard run waits, the background run proceeds.

Mark repeats this check throughout the run, not only at the start. A background run that is already in progress yields to a standard run that arrives between steps.

### Trigger priority considerations

Keep the following in mind when selecting a trigger's priority:

- Priority affects scheduling only when your instance is at or near its concurrency limit. When slots are available, both execution classes run immediately.
- Mark defers a background run instead of canceling it. The run retries until a slot opens.
- A priority change applies to runs created after the change. Runs already in progress keep their original execution class.
- When a trigger has no explicit priority, Mark uses the default for that trigger type.
- Priority applies to top-level runs. A nested workflow agent inherits the execution context of the parent run.

## Chat trigger

The **Chat Trigger** starts a workflow when you or a teammate sends a specific message or command in [Mark chat](docId\:dtNBEttEGVvkhNkwNypLM).

### Configure a chat input trigger

1. Enter a **Name**.
2. (Optional) Enter a **Description**.
3. (Optional) Select a **Priority** from the drop-down list. See [Trigger priority](docId\:pYeMYR_1QCBBfc6rGEwlR) for more information.
4. (Optional) Enter a **Helper Message**. This message displays when someone `@mentions` the agent in Mark chat to guide their input.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/97Pbkldposy2SDuEYQlqG_chat-trigger.png" size="40" isUploading="false" position="center" width="576" height="732" darkWidth="576" darkHeight="732" showCaption="false"}

:::Paragraph{indent="1"}
The **Preview** displays how your helper message displays to users in Mark chat.
:::

5. Click **Save**.

### Use cases for a chat trigger

The chat trigger is ideal for workflow agents to run on demand from Mark chat without a manual click or external system event. Use it for tasks such as clearing old data or generating reports.

## Scheduler trigger

The scheduler trigger starts a workflow automatically at a specific time or on a recurring schedule. This is useful for workflows that run consistently without manual intervention, like sending weekly reports or syncing data every night.

:::hint{type="info"}
**Note**

The scheduler trigger's time settings are in Coordinated Universal Time (UTC).
:::

### Configure a scheduled trigger

1. Enter a **Name**.
2. (Optional) Enter a **Description**.
3. (Optional) Select a **Product Instance**. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Mark instance.
4. (Optional) Select a **Priority** from the drop-down list. See [Trigger priority](docId\:pYeMYR_1QCBBfc6rGEwlR) for more information.
5. (Optional) Enter a **Trigger Message**. The trigger message is standard plain text written in natural language that the workflow sends to the next agents when the trigger occurs. No special syntax or templating language is required. Write your request exactly as you would type a chat message to an AI agent.
   - **Sending the message** – Type your instruction directly into the **Trigger Message** field. For example, *The target audience is Marketers.*
   - **Receiving the message** – The agent processes this exact text as its initial prompt and acts on its configured capabilities. If one of the following agents has an input variable of `target audience`, it uses the value `Marketers`.
6. Configure the one time trigger date or recurring time.
   - **One time trigger**
     1. Keep the **Recurring** toggle off.
     2. Enter a **Trigger Date** or click the **Calendar** to select a date.
     3. Use the **Trigger Time** drop-down lists to select a time. Times are listed in your local time zone.

        ::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/W-BY0BZXu8Ih4JIEwFbVM_scheduled-trigger-1.png" size="60" isUploading="false" position="center" width="646" height="986" darkWidth="646" darkHeight="986" showCaption="false"}
   - **Recurring – Standard**

     1. Toggle **Recurring** on.
     2. Select the **Standard** tab.
     3. Enter or use the arrows to select how often the trigger occurs.
     4. Select how often the trigger occurs from the drop-down list.
     5. Select which days the trigger occurs.
     6. Select an **End Type** from the drop-down list.
        1. If you select **Max Occurrences**, enter the number of occurrences.
        2. If you select **End Date**, enter the end date.
     7. Review the **Preview** and ensure the dates and times look correct.

     ::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/tsmuCNCDntZ-qtfn6RNAq_schedule-trigger-recurring.png" size="60" isUploading="false" position="center" width="642" height="1068" darkWidth="642" darkHeight="1068" showCaption="false"}
   - **Recurring – Advanced (Cron)**

     1. Toggle **Recurring** **on**.
     2. Select the **Advanced (Cron)** tab.
     3. Enter a **Cron Expression** for how often you want the trigger to occur. See [Advanced (Cron) expressions for the scheduled trigger](docId\:pYeMYR_1QCBBfc6rGEwlR) for information.
     4. Select an **End Type** from the drop-down list. Based on the end type you selected, complete the following:
        1. **No End** – Skip to step 5.
        2. **Max Occurrences** – Enter the number of occurrences.
        3. **End Date** – Enter the end date.
     5. Review the **Preview** and ensure the dates and times look correct.

     ::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/TVbJEdZL2nukNq8Fm_585_schedule-trigger-cron-job.png" size="60" isUploading="false" position="center" width="654" height="806" darkWidth="654" darkHeight="806" showCaption="false"}
7. Click **Save**.

### Advanced (Cron) expressions for the scheduled trigger

Cron expressions are a standardized way to define repeating schedules. They consist of five fields that represent a time pattern.

```text
* * * * *
| | | | |
| | | | └─ Day of week (0–6, where 0 = Sunday)
| | | └── Month (1–12)
| | └─── Day of month (1–31)
| └──── Hour (0–23)
└───── Minute (0–59)
```

The following table includes common cron expressions:

| **Goal**                          | **Cron Expression** | **Explanation**                      |
| --------------------------------- | ------------------- | ------------------------------------ |
| Run every day at midnight         | `0 0 * * *`         | At 12:00 AM every day                |
| Run once a week (Sunday)          | `0 9 * * 0`         | At 9:00 AM every Sunday              |
| Run once a month                  | `0 8 1 * *`         | At 8:00 AM on the 1st of every month |
| Run every other day               | `0 7 */2 * *`       | At 7:00 AM every two days            |
| Run every weekday (Monday–Friday) | `0 6 * * 1-5`       | At 6:00 AM, Monday through Friday    |

:::hint{type="info"}
**Note**

Use Mark to help you formulate your cron expression.

For example, enter *What would be the cron expression for running the job every night at 10 pm?*

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/uYFLbzN5UloKe-HG-Wgqy_ask-opal-for-cron.png)
:::

### Use cases for a scheduler trigger

A scheduler trigger is ideal when you want workflow agents to

- Run consistently without requiring manual intervention to start them.
- Automate maintenance tasks like clearing old data or generating reports.
- Align with business cycles, such as monthly billing or weekly marketing updates.

## Webhook trigger

The webhook trigger starts a workflow when an external system sends an HTTP request to a unique endpoint. Use this trigger to respond to events that occur outside of Mark. For example, a content update event in Optimizely Graph, a flag update in Feature Experimentation, or a build pipeline completion event.

See the following webhook documentation in other Optimizely One products:

- [Webhooks](docId\:l1fmyem53PgyeFhBqlqHe) in Campaign
- [Webhooks](docId:2OtscZ9kAb1eDBZvDuLac) in Content Marketing Platform (CMP)
- [Webhooks](docId\:znFZo3TtdhpV2Gef_FzQ7) in Feature Experimentation
- [Webhooks](docId:90hfpGkwLdqURm3GqdAsn) in Optimizely Graph
- [Webhooks](docId\:Lpb6hgxKhG7q92gwAJzEN) in Web Experimentation

### Configure a webhook trigger

1. Enter a **Name**.
2. (Optional) Enter a **Description**.
3. (Optional) Select a **Product Instance** from the drop-down list. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Mark instance.
4. (Optional) Select a **Priority** from the drop-down list. See [Trigger priority](docId\:pYeMYR_1QCBBfc6rGEwlR) for more information.
5. (Optional) Select your **Timezone** from the drop-down list. The agent uses the timezone when it talks about dates and times, like "today" or "this morning". If that the timezone is not known, the agent says so rather than guess. Systems calling this webhook trigger can override it by sending a Time-Zone header with an Internet Assigned Numbers Authority (IANA) name, for example `Asia/Dhaka`.
6. (Optional) Select the **Payload Content Type** from the drop-down list. This specifies the format of the data (payload) the webhook expects to receive. Common types include `application/json` (for JSON data). See [Example payload content types](docId\:pYeMYR_1QCBBfc6rGEwlR).
7. (Optional) Enter a **Payload Schema** to define the structure and data types of the expected payload. A schema helps validate incoming data and ensures the webhook processes information correctly. Enter this in JSON schema format.
8. (Optional) Enter a secret value for the **Auth Key** that authenticates incoming webhook requests (for example, a token or API key). This enhances security by ensuring only authorized senders can trigger the webhook.
9. (Optional) Select the **Auth Header Name** of the HTTP header that sends the auth key. Common examples include `Authorization` or `X-Webhook-Secret`.
10. (Optional) Enter the string template for the **Auth Header Format** to construct the header.
11. Click **Save**. The system generates the **Webhook URL** automatically.
12. Copy this URL and use it in the external system.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/r6zGeBHQoDqqfPB3jRxN7_webhook-trigger.png" size="60" isUploading="false" position="center" width="666" height="1744" darkWidth="666" darkHeight="1744" showCaption="false" indent="1"}

:::hint{type="info"}
**Note**

You cannot update the **Auth Key**, **Auth Header Name**, and **Auth Header Format** after saving the trigger. To edit them, delete the existing webhook trigger and create one with the correct fields.
:::

### Example payload content types

| **Content type**                    | **Parsed as**      | **Example header**                                |
| ----------------------------------- | ------------------ | ------------------------------------------------- |
| `application/json`                  | JSON object.       | `Content-Type: application/json`                  |
| `application/x-www-form-urlencoded` | Key and value map. | `Content-Type: application/x-www-form-urlencoded` |
| `text/plain`                        | Raw string.        | `Content-Type: text/plain`                        |

### Use cases for a webhook trigger

Choose the webhook trigger when you want workflow agents to start immediately in response to external events, without polling or manual action. The webhook trigger works well for real-time syncs, notifications, and event-driven automation.

## Email trigger

The **Email** trigger starts a workflow when an email is sent to the email address that you set as the **Trigger Recipient**.

The trigger activates only when the following conditions are met:

- An email is sent to the **Trigger Recipient**.
- The email matches the **Sender Filters** and optionally the **Subject Filters**.

This ensures that only valid or expected messages start the workflow.

The system does not support custom domains and Reply-To headers. Mark's domains use [DomainKeys Identified Mail (DKIM)](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail), [Domain-based Message Authentication, Reporting, and Conformance (DMARC)](https://en.wikipedia.org/wiki/DMARC), and [Sender Policy Framework (SPF) ](https://en.wikipedia.org/wiki/Sender_Policy_Framework)to maintain deliverability. For security, Mark restricts sending from arbitrary addresses.

:::hint{type="danger"}
**Warning**

Before using the email trigger, you must configure the email domain. See [Email domain](docId\:pe0pbUJveWrG8ewvZWDRE) for information. After you set your **Email Domain**, you cannot update it.
:::

### Configure an email trigger

Each workflow agent can have one email address recipient. Enter the following data and click **Save**.

1. Enter a **Short Description** for the email trigger.
2. (Optional) Select a **Product Instance**. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Mark instance.
3. (Optional) Select a **Priority** from the drop-down list. See [Trigger priority](docId\:pYeMYR_1QCBBfc6rGEwlR) for more information.
4. Enter the email address for the **Trigger Recipient**. This is the part before the "@" symbol.
   - Click **Copy** to copy the email address to your clipboard.
5. Define criteria to filter incoming emails based on sender's email address in the **Sender Filters**. Only emails matching these conditions trigger the workflow agent.
6. (Optional) Click **Add Filter** for **Sender Filters** to add additional filters.
7. (Optional) Click **Add Filter** for **Subject Filters** to define criteria to filter incoming emails based on their subject line. Only emails matching these conditions trigger the workflow agent. For example, you can require subject lines that contain *Approved* or *Request Details*.
   - (Optional) Select **Match case** to limit results to text with the exact capitalization you entered.
8. Click **Save**.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/EwG5nxFsTX4mjtEVXTTPr_email-trigger.png" size="50" isUploading="false" position="center" width="576" height="862" darkWidth="576" darkHeight="862" showCaption="false" indent="1"}

### Use cases for an email trigger

- **Approvals and sign-offs** – A reviewer sends *"approve"* or *"deny"*, and the workflow agent branches accordingly.
- **Vendor intake through email** – A partner emails a CSV or PDF to a monitored alias, and the workflow agent starts and processes the attachment.
- **Change requests with notes** – A stakeholder replies that an item needs changes with comments. The workflow agent routes back to the owner.
- **Lightweight ticket creation** – Inbound emails trigger triage, labeling, and assignment without a separate helpdesk.

### Difference between an email trigger and the `send_email` tool

The email trigger and the `send_email` tool serve different purposes.

- The **Email Trigger** starts a workflow agent when an email is sent to the automatically generated trigger address.
- The `send_email` tool sends emails from within a workflow agent. Send these emails to any external address. The tool is not limited to sending messages to the trigger address.

## Next steps

See [Create a workflow agent](docId\:KWaI2TBwD38sN7p74exoy).

:::hint{type="info"}
**Note**

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See [Turn generative AI off across Optimizely applications](docId\:X5U0kKD2azV5cIdNqwGNj).
:::