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.
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.
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.
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.
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.
HTTP webhook
App trigger
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
Process the new payment for {{payload.customerEmail}} and log it to the CRM.
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.
Before you start. The app you want to listen to must already be connected to your workspace. The source list only shows connected apps, so if yours is missing, connect it first and reopen the drawer.
1
Basics — name and source
Name the trigger and choose App trigger, the button labelled Gmail · GitHub · connected apps. The list shows only apps already connected to your workspace. Google services appear here rather than under a source of their own.
2
Choose event type and options
Select the app-specific event type. Some apps show dynamic option fields (e.g. workspace or channel IDs fetched live from the provider). These fields require an active provider connection. If the connection is revoked, save will fail until reconnected.If the app requires a connection and none is linked yet, a banner with a Connect app button appears.
3
Task, Filter, and When this trigger fires
Complete these sections as in the HTTP path. The App-trigger path shows four numbered sections rather than five, because webhook authentication does not apply.
4
Save and wire if needed
Click Create trigger. For apps that use their own webhook infrastructure, a post-save panel may appear with a callback URL and a one-time secret header name and value to paste into the provider’s dashboard, this step completes the subscription on the provider’s side.
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 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.
Payload templating with the double-brace syntax
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
Process the new payment for {{payload.customerEmail}} and log theamount ({{payload.amount}}) to the CRM under their account.
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}}.
Event data picker
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
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.
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)
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
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.
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
Reading the status badges
Status
Meaning
Received
Event arrived; awaiting processing
Ready
Event parsed and queued; awaiting claim by the worker
Claimed
Worker picked it up; agent run starting
Dispatched
Agent is actively running
Completed
Agent run finished successfully
Failed
Agent run threw an error; details in drawer
Filtered
Event did not match the filter rules; agent was not invoked
Expired
Event sat unclaimed too long and will not run
Cancelled
Run was stopped before completion
Diagnosing a trigger that fires but nothing happens
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
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.
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.
Thing
Behaviour
Task description
Plain language, with a generous character allowance
Filter toggle
Off by default, meaning every event runs
Event data
All fields forwarded when you make no explicit selection
Destinations
Depend on the agent’s configuration; an unconfigured agent shows Runs only
A trigger can be live and still appear to do nothing. Work through these in order rather than recreating the trigger.
What you see
What it means
What to do next
Trigger created, URL available
Live and listening.
Send a test event before wiring real traffic.
No events at all in the history
Nothing reached the trigger.
The problem is upstream. Check the URL, the method, and the authentication header on the sending side.
Events arrive but are marked filtered
The trigger received them and your filter excluded them.
Loosen the filter, or check the field names against a real payload.
Events arrive, nothing happens afterwards
The run happened but produced no visible result.
Check where the result was meant to go. An agent with nothing configured records the run and posts nothing.
An app trigger stops firing
The provider connection was revoked or expired.
Reconnect the app. Triggers that depend on it stay listed but cannot fire.
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.
Filtered is not broken
A filtered event means the trigger is working correctly and your rule excluded that event. Check the badge before concluding the trigger has failed.
Paste a real payload before adding filter rules (HTTP)
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.
Leave Event Data as 'All fields' unless token count is a concern
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.
Preview before connecting real traffic
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.
Use Bearer Secret authentication for any sensitive webhook
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.
Rotate the URL only when a secret is compromised
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.
Template the double-brace syntax sparingly
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.
Watch the 'Filtered' badge before assuming a trigger is broken
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.
Watch app connections, not just triggers
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.
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.
