Automation & Listeners

SupaNet does not only work when you are typing at it. It can react to things happening elsewhere, process incoming messages, and run jobs on a timer. You do not need to build any of this yourself - this page is just so you know what is possible and can ask for it.

Listeners: react to events

A listener is an automation rule: "when this happens, do this." SupaNet emits events whenever something meaningful happens — an artifact is created, a file is uploaded, a message arrives, or something is filed into a collection.

On the Listeners page (/listeners), you set up rules. For example:

• "When a new file arrives in the Data collection, run the Analyzer agent to summarize it."
• "When a message arrives from Slack, file it into the Support inbox collection."
• "When a to-do is marked complete, log it for later review."

Each listener specifies:

• Event — what you're listening for (e.g., file.created, message.received, meeting.recorded, or a wildcard like *). The dropdown shows three categories:
  • Common — built-in event types for core SupaNet objects (artifact, file, to-do, link, message, meeting).
  • Your tables — events from tables you've enabled as event sources (when a row is added).
  • Seen recently — any custom or one-off event types that have actually fired in your workspace. You can also type a custom event name if you want to listen for something that hasn't fired yet.
• Filters (optional) — narrow it down:
  • Collection — only items filed into a specific collection.
  • From source — only messages from a specific source (e.g., email or Slack).
  • Inbox — for message.received rules, target a specific mailbox (e.g. "when mail arrives in this inbox"). Leave blank to listen to all inboxes.
• Action — what to do when it matches:
  • Run an agent — call an agent with the event data as context.
  • Run a tool — invoke a tool directly (no model).
  • Add to collection — file the thing into a collection.
  • Log — record the match (useful for testing).

When a listener runs an agent, it learns the workspace timezone (set in Settings → Timezone), so if the agent needs to reason about time — "log this if it arrived today" — it uses your local clock, not UTC.

The Events page (/events) shows you the live stream of everything happening in your workspace — so you can see which events are firing and test your listeners before turning them on.

Automation health

For listeners, scheduled agents, and webhooks to actually run, SupaNet needs a background dispatcher and scheduler — cron jobs that tick once per minute. These are normally set up automatically when you deploy.

If you see a banner on the Listeners page saying "Automations aren't running," it means the background dispatcher isn't scheduled. Click the Schedule it now button to fix it. (Admins can also do this manually via the Listeners page health check.) Cron scheduling happens automatically on every deploy, so you should never need to do this unless you set up SupaNet by hand without running the deployment workflow.

Reacting to incoming messages

The Inbox is where all your messages live — email, Slack, WhatsApp, or anything you push in. When a message arrives, it emits an event, so you can set up a listener to react to it.

For example, you might listen for message.received and run a triage agent to categorize it, or file all Slack messages into a collection automatically.

See Inbox for how messages flow in.

Reacting to webhooks

Other systems can send information into SupaNet through a webhook - a private address that, say, your form tool or your CRM posts to when something happens. SupaNet can then save the data to a table, run a prompt, or run an agent against it.

Four modes (in order of precedence):

1. Save to table — the raw payload drops straight into a column of your table (deterministic, no AI, never skipped). If that table is an event source, a listener can then react to process it. Perfect for "store the raw data, then have an agent structure it afterward."
2. Call a function — the payload is validated and sent straight to a custom tool (deterministic, schema validation is the gate).
3. Run an agent — SupaNet runs an agent against the payload with its full toolset and access rules.
4. Run a prompt — SupaNet runs a plain prompt against the payload (AI-driven, subject to guardrails).

In plain terms: "when a new lead arrives, summarise it and file it" or "when this form is submitted, check it and flag anything odd." The event arrives, SupaNet does the work, and it is all recorded.

This is more direct than listeners — the webhook has its own configuration and can run immediately, whereas listeners react to internal events. Use webhooks for external systems; use listeners for things happening inside SupaNet.

When a webhook runs an agent, the agent knows the workspace timezone (set in Settings → Timezone), so it answers questions like "is this today?" or "when is the next Tuesday?" in your local time, not UTC.

Running on a schedule

SupaNet can run an agent on a repeating schedule - every morning, every hour, whatever you need. The agent runs using its own instructions each time; you can optionally add extra direction for a specific run if needed. A classic example is "every morning, gather X and email me a summary." You set it up once and it just keeps happening.

Timezones: By default, scheduled agents (and all automations) reason about the current date and time in UTC. If your team is elsewhere, set the workspace timezone in Settings → Timezone — then every agent, listener, webhook, and Slack reply will know the correct "today" and "now" in your local time. New schedules will default to this timezone; existing ones keep theirs unless you change them manually.

Watching agents run

Once you have agents set up, you might want to see what they are actually doing. Click the Runs button next to any agent on the Agents page to open its observability dashboard at /agents/:id.

The dashboard shows:

• Recent runs — a list of the last 50 times the agent ran, whether from chat, a schedule, a webhook, or Slack. Each run shows its status, trigger, final output, tool calls, duration, and when it happened.
• Expand a run to see its step-by-step timeline — each model turn and tool call in order, with the tool's input and output so you can debug what went wrong (or right).
• Technical detail toggle — hides per-step tokens and costs by default so non-technical users see a cleaner view, but admins can flip it on to see the full accounting.
• Live updates — if a run is currently in progress and you expand it, the steps tick in real time so you can watch the agent work.

This is how you answer "Did my scheduled agent actually run this morning?" or "Why did the webhook agent choose that tool?" — see the full trace of what happened.

The activity feed

Whenever SupaNet does something on its own - uses a tool, processes a webhook, runs a scheduled job, or dispatches a listener - it writes a line to the activity feed. This gives you a live, running record of what the system has been up to.

Chat failures are also logged to the activity feed, so if something goes wrong when you send a message, you'll see what happened without having to dig around. Use the Chat filter to see only chat activity.

What you see in the feed respects your permissions: you see your own activity, and admins can see everything across the workspace.

Why you would care

Automation is what turns SupaNet from "a chat I visit" into "a teammate that is always on." The chat is for when you are present; webhooks, schedules, and listeners are for when you are not. If you find yourself doing the same small task over and over, that is usually a sign it could be automated - ask whoever runs your workspace.