Triggers: wake your agent when something changes
Roma tells your agent the moment a list changes, instead of it checking.
A trigger wakes your agent the moment something on your lists changes, instead of the agent finding out on its next scheduled run. You pick a list and a change to listen for, and where to send it. Each time it fires, your agent gets an event with the item as it is now and what changed, within a second. Triggers live on the Automations page, beside your automations, as the third answer to when an automation should run.
What a trigger listens for
The form asks which change, on which list:
A property changes. Then you pick the property and, if you like, what it becomes. "Status becomes In progress on Releases", "Stage becomes ready to go on Properties", "Due date changes on Tasks". Any value, or one value.
An item is added.
An item is deleted.
Anything about an item changes.
A list is always picked, so an agent is never flooded with every change in your account. Sam keeps a Releases list with a Stage property. His trigger on Stage becoming "ready to go" fires once when that happens and stays quiet for every other edit on the list.
The developer side reaches a few more events, an item moved or restored, a list created, changed or deleted, an automation finishing, and your reply to the agent in a task chat. The whole list is on /developers/events.
Where the event goes
Two ways, chosen when you create the trigger:
Agent polls, the default. Nothing to set up on Roma's side but an API key for your agent. Each change becomes an event your agent asks for whenever it likes. Roma holds the request open up to 25 seconds and answers the moment an event waits, and the events queue on Roma's side until fetched, so a laptop that was asleep picks up where it left off. This is the way for Claude Code or Codex on your Mac, or a script.
Webhook. An address on the internet that accepts a request: your own server, or a Claude Routine's fire URL with its bearer token. Roma sends a signed request within a second of the change. If the address does not answer, Roma tries again after 1 minute, 1 hour and 6 hours, then the trigger pauses itself as Failing. Fix the address with Edit, or press Resume to try again.
ChatGPT has a third way. On Plus and up, a Work chat on chatgpt.com can subscribe to Roma's events by itself, with Roma added on the web Plugins page. Ask it to subscribe, and the subscription shows on your Automations page like any other trigger. Connect ChatGPT and Codex to Roma.
Set one up, step by step
On the Automations page, press New automation.
Under "When should the automation run?", choose On a change, beside On demand and On a schedule.
Pick Which change and the List. For a property, pick the Property and what it Becomes, Any value or one of them. The line under the menus reads back what you made: "Runs when Stage becomes ready to go on Releases." The name follows your picks unless you type one.
Under "What should it do?", choose Agent polls or Webhook. A webhook takes the URL and, optionally, a bearer token.
Save. The trigger's page opens.
For a webhook, copy the signing secret from the top of the page now. It is shown only this once, and your server uses it to check that each request came from Roma. For a poll, the page lists what your agent needs: an API key from Settings, then Connections, then API keys (API keys and signing in from an agent), the address to poll with that key, and a loop that polls and acts on each event. The loop, with examples for Claude Code, Codex and a script, is on /developers/events. An agent can also create a trigger for itself, from its own Roma connection. Ten triggers per account.
The trigger's page
The page is the twin of an automation's. The pill at the left of the bar reads Active, Paused or Failing, and opens Pause or Resume. Edit opens the same two cards you filled in, with the transport settled. The menu at the right has Delete automation, since to the page every row is an automation.
Two cards say what it does: When it runs, as the sentence your picks make, and What it does, the address or the poll with what the agent needs under it. Under them, Previous runs lists every delivery: when it rang, one line saying what happened ("Ship the release moved from To do to In progress"), and how it went, delivered with the answer's code, failed with a retry pending, waiting for the agent's poll, or gave up. Open a delivery to see the data the agent received and to Resend it. Send a test sends a real sample event through the trigger's own transport, so you can see the loop work before anything changes on the list.
On the Automations page, triggers sit in the same list as your automations, each row with its state and how its last delivery went. What an automation is explains the rest of that page.
What the agent receives
Every event carries four things. The item as it is now, with its title, list, status, properties and body, so the agent can usually act without a second read. What changed, with the earlier value and the new one for each field. Who made the change: you, the operator or an agent. And one sentence describing it, the item quoted and the person named. The agent then reaches Roma back through the connection it already has, reads what it needs, does the work in the item's body and posts in the item's chat if something needs you. What an agent can and cannot do in your account has those rules.
Replying to an agent in a task chat
When an agent that a trigger wakes posts in a task's chat, its post offers Reply. Your reply reaches that agent as an event and does not go to the operator. A message typed without Reply goes to the operator as usual. An agent that reads the chat on its own next run can say so when it posts and gets the same Reply. Otherwise its post is a note with no Reply on it. The conversation on a task or note explains that chat.
Questions people ask
Does a trigger run my agent for me?
No. A trigger tells your agent that something happened and hands it the item. The agent has to be listening, with a loop that polls or an address that accepts the request, and does its work through its own Roma connection. A Claude Routine is the one case where the webhook starts the agent itself, in the cloud, with nothing of yours running anywhere.
What if my laptop was asleep when the change happened?
With Agent polls, the events wait on Roma's side until your agent asks for them. When the laptop wakes and the loop polls again, it gets everything since its last poll, in order, and nothing is lost.
Why did my trigger stop?
A webhook whose address did not answer is retried after 1 minute, 1 hour and 6 hours. After that the trigger pauses itself and reads Failing, and the delivery shows what the address answered. Fix the address with Edit, which brings it back, or press Resume to try the same address again. A trigger that reads Paused is one you paused yourself.
Can I see what was sent?
Yes. Every delivery is listed under Previous runs on the trigger's page. Open one to read the data exactly as the agent received it, the item and what changed, and press Resend to send it again.