Workflow agent triggers

Workflow triggers start an Optimizely Opal workflow agent 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.

Important information about triggers

Connections

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

If you change the connection to an associated instance after a trigger is created, the trigger may continue to reference the original instance it was configured with. 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 section in the Get started with Optimizely Opal for administrators documentation for information. 

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 Opal 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, you should enter complete and accurate descriptions for all fields, including those in specialized agents and tools.

Chat Input trigger

A Chat Input trigger is an event that starts a workflow agent when a collaborator sends a specific message or command in Opal Chat. When the workflow agent detects that a collaborator has entered specific words or patterns in the chat, it automatically starts the remainder of the workflow process.

Configure a chat input trigger

1. Enter a Name.

2. (Optional) Enter a Description.
    

   

3. Click Save.

Use cases for a Chat Input trigger

The Chat Input trigger is ideal for workflow agents that need to run on demand and directly from chat without requiring a manual button click or external system event. It creates a seamless experience for collaborators, letting them start complex, multi-step automations by typing a request.

Scheduler trigger

The Scheduler trigger starts a workflow agent 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.

Configure a scheduled trigger

1. Enter a Name.
2. (Optional) Enter a Description.
3. (Optional) Enter a Trigger Message. The Trigger Message is sent to the next agents in the workflow when the trigger occurs. For example, the Trigger Message could contain data or variables for the agents to act on.
4. Configure the one time trigger date or reoccurring 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. 

        

   • Reoccurring – 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.

        

   • Reoccurring – 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 for information.
     4. 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.

     5. Review the Preview and ensure the dates and times look correct.

        

5. 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.

* * * * *
| | | | |
| | | | └─ 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:

You can use Opal 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?

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.

By combining the scheduler with other workflow agent logic, you can create powerful, automated processes that run exactly when needed.

Webhook trigger

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

Configure a Webhook trigger

1. Name – Enter a name.
2. (Optional) Description – Enter a description.
3. Payload Content Type – Enter the payload content type that defines how the request body is formatted and parsed.
4. (Optional) Payload Schema – Enter the payload schema to validate the payload shape before the workflow agent runs.
5. (Optional) Auth Key – Enter a secret value that authenticates the sender (for example, a token or API key).
6. (Optional) Auth Header Name – Enter the HTTP header to carry the auth key.

7. (Optional) Auth Header Format – Enter the string template for how to construct the header.

   

8. Click Save. The system automatically generates the Webhook URL for you. Copy this URL and use it in the system you want.

Example payload content types

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 is perfect for real-time syncs, notifications, and event-driven automation.

Email trigger

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

The trigger activates only when

• 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. Opal's domains use DomainKeys Identified Mail (DKIM), Domain-based Message Authentication, Reporting, and Conformance (DMARC), and Sender Policy Framework (SPF) to maintain deliverability, and the system restricts sending from arbitrary addresses for security.

Before using the email trigger, you must configure the email domain.

See Email domain configuration 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. Short Description – Enter a description for the email trigger.
2. Trigger Recipient – Enter the email address. This is the part before the "@" symbol.
   • Click Copy to copy the email address to your clipboard.
3. Sender Filters – Define criteria to filter incoming emails based on sender's email address. Only emails matching these conditions trigger the workflow agent.
4. (Optional) Subject Filters – 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.

5. Click Save.

   

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. You can send these emails to any external address. It is not limited to sending messages to yourself.

Next steps

See Create a workflow agent.