Skip to main content
EVENT-DRIVEN AGENTS

​
Your agent picks up the phone when the world calls.

Wire any agent to an inbound HTTP webhook or to a connected app. No polling script, no relay service, no cron job: the agent wakes the instant an event fires and leaves a full audit trail behind.

The filter layer

​
Watch a payload pass, or get dropped.

Every inbound event runs through your filter rules before the agent wakes. Pick a payload and see exactly what the filter decides.

Filter rule (All conditions must match)
payloadamountgreater_than500ANDpayloadstatusequals”paid”
amount: 1200status: “paid”customer: “[email protected]”
amount: 80status: “refunded”customer: “[email protected]”
Both conditions matched. Instruction rendered. Agent dispatched.
amount 80 is not greater than 500. Agent was not invoked. Status: Filtered.
trigger · stripe-payments · rendered instruction
taskProcess the new payment for [email protected] (amount: $1200) and log it to the CRM.
tool · memory_search · “[email protected]”
agentPayment logged under Alex’s account. Invoice marked paid. CRM updated.
filterEvent evaluated. Amount 80 is not greater than 500. Condition failed.
event · status: Filtered · agent not invoked
logRecorded in Recent events with its filter outcome.
No false wakes. Filters run before the agent is invoked. A filtered event costs nothing and never starts a run.
AND or OR logic. Choose All conditions (every rule must match) or Any condition (any single rule is enough) to build compound rules.
Preview first. Paste any payload into Preview with sample payload and confirm the filter decision before a single real event arrives.
Under the hood

​
Five stops from webhook to completed run.

Every inbound event moves through a deterministic lifecycle. Watch it pulse through the stages below.

Event arrived and persisted. Not yet processed.
Parsed and queued. Awaiting worker claim.
Worker picked it up. Agent run starting.
Agent actively running. Tool calls in flight.
Run finished. Result delivered. Transcript linked.
ReceivedReadyClaimedDispatchedCompletedFilteredFailedExpired
Delivery is not instantaneous. An event that reaches Actionist is queued before a worker picks it up, so allow for a short lag between the event firing and the agent starting. Design genuinely time-critical workflows with that in mind.
The concept

​
Stop polling. Start reacting.

A trigger is the configuration that connects an external event source to an agent. Every time a matching event arrives, Actionist hands the event data to your agent along with a natural-language task, and the agent runs.

The old way

Write a polling script. Deploy a webhook relay. Schedule a cron job. Check your inbox manually. Every approach involves infrastructure you have to build, host, and monitor before your agent sees a single byte of data.

With triggers

Pick a source, write a task description in plain English, and click Create trigger. Actionist handles the subscription, receives the event, renders your instruction, runs the agent, and logs the whole thing, while you do something else.
Two vocabulary terms used throughout this page: trigger is the saved configuration (source + task + filter + delivery settings); event is each individual inbound payload that the trigger receives. One trigger receives many events over its lifetime.
Triggers work in the web app. Creating a trigger, managing it, and reading its event history are all available at Agent Studio → Triggers, with no desktop install required.
Sources

​
Two ways the world can call your agent.

The creation dialog offers two source buttons, and they set up differently. Select below to see what each involves.

HTTP webhook · setup
1.Name the trigger (e.g. New Stripe payment). Select the HTTP webhook tile.
2.Choose auth: Public (no auth) or Bearer secret backed by the Credentials Vault.
3.Save. Copy the generated webhook URL from the trigger row.
4.Paste the URL into Stripe / GitHub / Typeform, or any service that sends webhooks.
accepts any JSON payload · bearer secret checked against the Authorization header

Changing a saved trigger from one source type to the other is not something to rely on. If you need to switch, delete the trigger and create a fresh one.

App trigger · Gmail · GitHub · connected apps
1.Choose App trigger, labelled Gmail · GitHub · connected apps, then pick the app. Only connected apps appear.
2.Choose the app-specific event type. Dynamic option fields load from the provider live.
3.Save. A post-save panel may show a callback URL and one-time secret header to paste into the provider’s dashboard.
Google services live here, not in a separate source · connect banner if no active connection

App triggers need the app connected first. Gmail and other Google services are reached through here rather than through a source of their own. If the provider connection is revoked, save will fail until you reconnect.

Get started

​
Create a trigger.

Open your agent in the studio, select the Triggers tab, and click Create trigger. An HTTP webhook shows five numbered sections. An App trigger shows four, because it has no webhook authentication step of its own.

1

Basics — name and source

Give the trigger a name (e.g. New Stripe payment). Select the HTTP webhook tile. Toggle Enabled on to start receiving events immediately after save.
2

Task — what the agent should do

Write a plain-language task description (up to 5,000 characters). This tells the agent what to do with each event. Use {{payload.fieldName}} to embed live values from the webhook body, for example:
task description
The Event Data picker below the field controls which payload fields the agent receives. Without a pasted sample payload, toggle Send the full payload to the agent on to forward everything.
3

Filter — scope the events that matter (optional)

Toggle Filter incoming events on if you only want the agent to run on a subset of payloads. Add one or more conditions with Add condition, choose All conditions (AND) or Any condition (OR), then pick a field path, an operator, and a value.Leave the toggle off to run on every event, useful for prototyping.
4

Webhook — authentication

Choose Public (no auth) for open integrations or Bearer secret for anything sensitive. If you choose bearer secret, pick an existing credential from your vault or click + Create new credential to create one inline. The credential value is checked against the request’s Authorization header on every call, so producers send it the way they would send any bearer token.
5

When this trigger fires: where the result goes

The final section is headed When this trigger fires. Which destinations it offers depends on how the agent is set up; an agent with nothing else configured shows Runs only, meaning the run is recorded and nothing is posted anywhere. Check what your agent actually offers here rather than assuming a destination exists.
6

Save

Click Create trigger. The trigger appears in the list. Expand the row to see the Webhook URL with Copy URL and Copy curl buttons. Paste that URL into your external service.
agent studio · New Stripe payment · Create trigger
Create trigger✕
Basics
NameNew Stripe payment
Source
HTTP webhookApp trigger
Task
Process the new payment for {{payload.customerEmail}} and log it to the CRM.
Filter On
payload.amountgreater_than500
Webhook auth
Public (no auth)Bearer secret
When this trigger fires
Runs only
Create triggerCancel
Create trigger drawer: HTTP webhook mode, all five numbered sections
The task section

​
Shape what the agent sees.

The Task section controls three things: what the agent should do, which payload values to embed in the instruction, and which event fields to pass alongside it.

Task description

Write a plain-language instruction for the agent. Up to 5,000 characters. Tell it what to do with the event, who to notify, where to store the result. The placeholder shows a minimal example:
Event details are automatically appended to what the agent receives. You do not need to describe the payload schema in the task description itself. Use the task description for the goal, not the data.
Embed live payload values directly in the instruction using {{payload.fieldName}} tokens. When the trigger fires, each token is replaced with the matching field from the incoming event before the agent sees it.
example instruction
What happens when a field is missing: the token renders as an empty string. Over-templating on fields that are not always present in the payload can produce confusing instructions. Use tokens only for fields the provider reliably sends every time.The path supports dot notation for nested fields: {{payload.customer.email}}.
Below the task description, the Event data section controls which fields from the incoming event are included in the JSON block the agent receives alongside your task description.Choosing fields: the picker shows a catalog of fields built from a sample payload. Checked fields are sent; unchecked fields are omitted. The count summary shows how many are included:
Leave it as “All fields” unless context window size is a concern. When no explicit selection is made, all fields are forwarded and new fields added to the event schema in the future are automatically included. An explicit selection is frozen. New fields require re-saving the trigger to include.For HTTP triggers without a sample payload: toggle Send the full payload to the agent on to forward every field from the webhook body. Only top-level fields can be individually selected; nested objects are always sent wholesale.
If no fields are checked and “All fields” is also off, the agent receives only your task description. No event data at all. The picker shows a warning: “The agent will only see your task description, not any event data.”
Task · Event data picker · Gmail trigger
Event data3 of 5 fields included
FromRecommended
SubjectRecommended
Email bodyRecommended
Message IDOther
Thread IDOther
Agent input preview
Summarize the email and add it to my notes
Event data picker, 3 of 5 Gmail fields selected with agent input preview
Filter section

​
Only wake the agent when it matters.

High-volume event sources like webhooks can fire hundreds of events per day. The filter layer lets the agent sleep through the noise and act only on the events you care about.

Toggle Filter incoming events on to add rules. The toggle hint describes the default: “Off = run on every event. On = only run on matching payloads.” Choose All conditions (AND (every rule must match) or Any condition (OR) any rule is enough).

equals / does not equal

Exact string or number match. Works on any field type.

contains

Substring match for string fields. Not available on boolean or object fields.

greater than / less than

Numeric comparison. Only available when the field type is a number.

exists

Checks whether the field is present in the payload at all. Use it to gate on optional fields.
For HTTP triggers, paste a sample payload before building filter rules. The Choose a field… path picker builds its suggestions from the sample. Without one, you can only type custom paths manually (e.g. payload.x.y).
The preview evaluates your filter with the same rule engine the live dispatch path uses, so the two cannot drift apart. What you see in the preview is what fires live.
Test it

​
Verify before you go live.

Two testing tools, two different guarantees. Use both before sending real traffic.

​
Preview with sample payload

The Preview with sample payload panel renders the exact instruction and evaluates every filter rule against any JSON you paste. It makes no model call and saves no event, so you can run it as often as you like.

1

Open the trigger detail

Click the trigger row in the Triggers list to expand the detail panel.
2

Paste a sample payload

In the Preview with sample payload section, paste a representative JSON payload: a real webhook body, a copied event from your provider’s dashboard, or a hand-crafted example.
3

Click Preview

The panel instantly shows two things: the rendered instruction (with all {{payload.x}} tokens resolved), and the filter result:
  • Pass, would dispatch
  • Fail, event would be filtered (the agent would not run)
  • No filter configured (filter is off)

​
Run live test: a real end-to-end run

Once the preview looks right, fire a real end-to-end test with Run live test. Unlike the preview, this creates a real event and actually runs the agent.

Run live test creates a real event and runs the agent. If the agent can write to external systems (send email, update records) those writes will happen. Ensure the agent’s approval mode is set appropriately before running.
1

Enable the agent

The Run live test button is disabled when the agent is off. Enable the agent in the studio first.
2

Click Run live test

Confirm the dialog, which warns: “This creates a real event and runs the agent.”
3

Follow the run

A toast confirms: “Live test fired. Open the chat session to follow it.” Switch to the Recent events tab to watch the event progress through statuses in real time.
trigger · stripe-payments · Preview with sample payload
Sample payload
Preview
Rendered instruction
Process the new payment for [email protected] (amount: $1200) and log it to the CRM.
Filter result
Pass, would dispatch
Preview with sample payload: tokens resolved, filter result: Pass
Diagnostics

​
Every event leaves a trace.

The Recent events tab on each trigger keeps a full log of every inbound event: its status, the rendered payload, the filter outcome, and a direct link to the agent run transcript.

trigger · stripe-payments · recent events
event · 10:42 · amount: 1200, status: paid
10:42Received → Ready → Claimed → Dispatched → Completed. Run transcript linked.
event · 10:55 · amount: 80, status: refunded
10:55Filtered: amount 80 is not greater than 500. Agent not invoked.
event · 11:03 · amount: 2400, status: paid
11:03Received → Ready → Claimed → Dispatched → Completed. Payment logged to CRM.

The table auto-refreshes every 5 seconds so you can watch a live test progress in real time. Click any row to open the Event detail drawer.

What the event detail drawer shows

  • Payload: the raw event body, with sensitive keys automatically redacted
  • Filter result: which rule passed or dropped the event
  • Dispatch info: the agent, model, and run metadata
  • Open chat session: a direct link to the full agent run transcript for completed or failed events
If a trigger receives events but the agent never seems to run, the most likely cause is that events are being filtered. Check the Recent events tab for rows with a Filtered badge and click the row. The drawer shows exactly which filter condition dropped it.
trigger · stripe-payments · Recent events
TimePayloadStatus
11:03amount: 2400, status: paidCompleted
10:55amount: 80, status: refundedFiltered
10:42amount: 1200, status: paidCompleted
10:18amount: 560, status: failedFailed
10:02amount: 3100, status: paidReceived
Event detail
Payload
Filter result
Filtered out, amount less than 500
Open chat session
Not available. Agent was not invoked
Recent events. Mixed status badges with detail drawer open on a Filtered row
Operations

​
Keeping triggers healthy.

​
Rotate the webhook URL

Rotate the URL when a secret is compromised or when you want to revoke access from a specific producer. The old URL stops accepting requests the moment you confirm.

1

Select the trigger row

Expand the trigger in the list to see the detail panel.
2

Click Rotate URL

A confirmation dialog appears. Read it before continuing: rotating invalidates the current URL.
3

Confirm

Confirm the rotation. The new URL appears immediately. Update every external producer before they send the next event.
Rotation takes effect with no grace period. Any request sent to the old URL after you rotate will be rejected, so plan for it, especially with high-volume producers.
Reference

​
Limits and defaults.

Backend limits such as maximum payload size, event time-to-live, payload retention, maximum run duration, dispatch interval, deduplication window, and lookback are not surfaced anywhere in the trigger UI. Rather than publish figures we cannot verify from the product, this page omits them. Ask the team if you need a guaranteed number for a specific limit.
States and controls

​
Trigger states and silent failures.

A trigger can be live and still appear to do nothing. Work through these in order rather than recreating the trigger.

Why a save fails on an app trigger

Option fields on app triggers are fetched live from the provider. If the connection is revoked, those fields cannot load and the save is rejected. Reconnect the app, reopen the drawer, and select the options again.
A filtered event means the trigger is working correctly and your rule excluded that event. Check the badge before concluding the trigger has failed.
Tips

​
Best practices.

The Choose a field… path picker and the Event Data Picker both build their suggestions from the sample payload you provide. Without a pasted sample, only top-level keys appear and you cannot get field-level operator suggestions. Paste a real payload first, then build the filter.
The all-fields setting (undefined in the data model) auto-includes fields added to the event catalog later. An explicit selection is frozen. Any new fields the provider adds require you to re-save the trigger to include them. Prefer all-fields for low-stakes triggers; use an explicit selection only when the payload is large enough to cause context window issues.
Paste a representative payload into Preview with sample payload and confirm both the rendered instruction and the filter result look right. It makes no model call and saves no event, so there is no reason not to use it. Keep it distinct from Run live test, which creates a real event and runs the agent for real.
Store the secret in the Credentials Vault; the credential’s value is checked against the request’s Authorization header on every call. Public (no auth) is fine for low-stakes event buses; anything involving PII or financial data should always use bearer secret.
Rotation takes immediate effect with no grace period. Update all external producers before rotating if you can. Not after. If you are responding to a leaked secret and cannot coordinate, accept a brief delivery gap and update producers immediately after rotation.
Missing tokens render as empty strings silently. Over-templating on fields that are not reliably present produces confusing agent instructions. Use tokens only for fields your provider sends consistently on every event of that type.
If the trigger receives events but the agent never runs, check the Recent events tab for Filtered status rows. The Event detail drawer shows exactly which condition dropped the event, usually a value mismatch or a field that was not present in the payload.
An app trigger depends on a live connection to the provider, and provider connections can be revoked without warning by the user, by a password reset, or by a security policy. When a connected app stops delivering events, check the connection before you start debugging the trigger itself.
Real-world wins

​
The business moves while you are elsewhere.

Three event-driven triggers that close the gap between something happening and your team knowing about it.

Dario · Sales
New-lead webhook fires the moment a form submission lands. Dario’s agent reads the payload, checks the CRM for context, and drafts a personalised intro email: ready to review before the lead has closed the tab.
live in < 2 min after the first webhook fires
Felix · Finance & Ops
Gmail: New message with “invoice” in the subject wakes Felix’s agent. It extracts the amount and due date, logs them to the expenses tracker, and schedules a payment-reminder task for three days before the deadline.
saves ~3 hrs/wk on manual invoice triage
Sam · Solo founder
Drive: File created in the Contracts folder triggers Sam’s agent. It reads the filename and folder, adds a needs-legal-review flag to the project tracker, and posts a summary to the legal Slack channel. All before Sam is back from the meeting.
zero manual handoffs on contract intake

You were in a two-hour meeting. Three things happened in the world. Your agents dealt with all of them.

illustrative · Triggers · Actionist docs
Always on

​
Turn your agent into an autonomous responder.

Pick a source, write a task, and let the world wake your agent instead of you.

Open the DashboardEmail the team

Event-driven, not polling-based, with no infrastructure to host or monitor.
Filter before dispatch · Full audit trail · Works in the web app.

Keep going

​
Next steps.

Schedules

Time-based automation, the complement to event-based. Recurring jobs and timezone-aware scheduling, with no cron syntax.

Credentials

Store bearer secrets and OAuth tokens in the Credentials Vault, referenced by triggers without exposing raw values.

Agents

Configure approval mode and enable the agent. Run live test stays disabled until the agent is on.

Marketplace

Browse and connect the apps that provide App trigger sources, and see what events each one can fire on.