Triggers

Triggers convert events from the outside world into work items the Runbook can act on. Pick the source that matches how work shows up, then point it at this App.

Audience: builders

Open the Triggers tab

Inside an App, the Triggers tab carries a rail of existing triggers on the left and the editor on the right. Each row shows the trigger title, kind, and an Active or Paused badge. The page subtitle is direct about the job: "Choose what should start work."

The flip switch in the trigger hero turns a trigger on and off without deleting it. Use Paused to stage a trigger before going live, or to quiet a noisy source while you investigate.

Pick a trigger kind

Click New

The New button at the top of the rail opens the editor in create mode. The default source is whichever your App already uses; pick a different one from the source picker if you need to.

Choose the source

The six kinds the platform ships today:

Slack. Watch a channel or DM and create a work item per inbound message.
Teams. Watch a Teams channel or personal chat.
Email. Bind a mailbox and create a work item per inbound email. See Bound email for the full pattern, including templates and reply behavior.
OneDrive and Google Drive. Watch a folder. New or modified files become work items. Toggle Include subfolders for nested watches.
Webhook. Receive HTTP POSTs at a generated URL. Each post becomes a work item.
Schedule. Fire on a cadence configured at the workspace level.

Name the trigger

Use a name your reviewers will recognize on the work items list. "AP inbox watcher" beats "Trigger 1".

Configure the source

Each kind has its own short config section. The form blocks Save until the source has what it needs (a mailbox, a folder, a Slack conversation, and so on).

Save

The Create trigger button writes the trigger and brings the rail row online. If the Active toggle is on, the platform starts watching immediately.

Webhook triggers

After you save a webhook trigger, the editor shows a read-only URL like /api/v1/webhooks/app-triggers/<trigger-id>. POST a JSON body to that URL and the platform creates a work item.

Use the optional field paths to pull structure out of the post. Each path is a JMESPath expression against the JSON body.

Title path. Pulls a human-readable title for the work item. If blank, the platform generates one.
Payload path. Pulls the body the Runbook reads. If blank, the Runbook sees the whole request body.
Metadata path. Pulls extra context that rides alongside the payload.
Existing work item key path. Pulls a stable id. Reposts with the same id update the existing work item instead of creating a new one. Use this when the upstream system retries.

The webhook URL is generated, not configurable. Save the trigger first, then copy the URL into the upstream system. Treat the URL itself as the credential and rotate the trigger if it leaks.

Scheduled triggers

Pick Schedule when you want the App to wake up on a cadence. The cadence rule lives at the workspace level: the editor lets you name the trigger and toggle it on or off, but changing the schedule itself is an admin action. The editor surfaces a banner that says so.

Inbound email

Email triggers convert inbound mail into work items with structured input (subject, sender, body, attachments, threading metadata). The mailbox has to be bound to the Project first. See Bound email for the prerequisites, the binding step, and how the Runbook reads the inbound work item.

Slack, Teams, and shared drives

Slack, Teams, OneDrive, and Google Drive triggers all reuse a credential you have already bound at the Project level. See Integrations for the binding step.

Once a credential is bound, the picker shows the rooms or folders the credential can reach. Optional Instructions travel with each work item so the agent has the same standing context every time a message or file lands.

API ingest

Any client with Project credentials can POST to the Project's work items endpoint to create one directly. Use this for systems that already speak HTTP but do not fit the webhook or email patterns: cron jobs running in your own infrastructure, batch loaders, or scripts that import a backlog.

API ingest is the right tool when the upstream system needs to know whether the work item was created. Webhook triggers fire and forget; API ingest returns the work item id in the response.

Manual work item creation

The Work items tab on the App has a Create work item composer for human-initiated runs. The fields you see there come from the Runbook's input contract. See Inputs, outputs, and work item contracts for how the contract gets defined.

Manual creation is only available once the App has a published Runbook. Until then, the composer is gated with a hint pointing you back to Review and publish.

Retry and back-pressure

The platform queues work items and runs them against the App's published workflow. Inbound traffic does not block while a previous work item is still in flight; each work item lives on the queue with its own status.

Retries and back-pressure are handled per-trigger by the platform. Look at the work item's last error in the Work items tab to see why a specific run failed, and use Rerun to put a work item back on the queue.