The problem
Wire a webhook straight to the agent it starts and every consumer needs its own registration with the provider. A second legitimate reader of the same GitHub deliveries, such as a second agent, an audit copy or an outside system, means a second URL, a second signing secret, and a second place where a delivery can be lost or checked differently. Providers also disagree on everything a platform needs to know about an event: how it is signed, where its id is, what kind of event it is, which conversation it belongs to. Handling that in code per provider spreads through intake, triggers and the UI. And providers retry, so something has to stop a redelivered webhook from running the agent twice.How AgentArea approaches it
A stream is a workspace resource. It has a name, unique in the workspace, a description, and a kind:custom for the streams you create, platform for
the one the platform writes. Reading, editing and deleting a stream are
separate permissions in the authorization graph, checked per stream, and
creating a stream grants it to its creator. A stream cannot be deleted while a
trigger subscribes to it or a forward writes into it.
Sources come from the catalog. A source is an instance of a catalog entry,
listed by GET /v1/workspaces/{workspace}/streams/source-types. The entry
declares how its events arrive (webhook, poll or both), which credentials
and settings a source needs, how a webhook is verified, how a provider’s
endpoint check is answered, and where each event’s kind, key, session and
sender are found in the request. The shipped catalog has entries for generic
webhooks, GitHub, Slack, Telegram, Linear, Discord, Stripe, Sentry, Gmail,
Teams, email, IMAP, RSS and MCP Events. A credential is a reference to a
workspace secret, or a secret the platform issues and shows once.
- A webhook source gets an unguessable URL,
/webhooks/{webhook_id}on the API host. A request that passes the entry’s verification is answered202with"status": "accepted", or"duplicate"for a repeat, before anything reacts to it. A failed verification is a401. - A poll source is fetched by the event service on the entry’s interval, from the cursor it stored after the last fetch.
- An MCP Events source reads the events of an MCP server instance in the
same workspace that offers them, by polling it or through a webhook
subscription the event service keeps at that server and renews before it
expires. When subscribing fails, or the server ends the subscription, the
error is shown on the source and the next attempt waits: the wait starts at
AGENTAREA_EVENT_POLL_INTERVAL(5 s by default), doubles after each failure, and stops growing at 1 hour. An event whose payload is an AgentArea event envelope (another stream read through the AgentArea MCP server) keeps the original kind and continues its chain: the samecorrelation_id, the original event ascausation_id, and its depth plus one. A loop back through the MCP server therefore stops atAGENTAREA_EVENT_FORWARD_DEPTH. Without an inner kind, the event is named by its MCP event type.
A webhook request may be up to 25 MB. A workspace may record
AGENTAREA_EVENT_WRITE_QUOTA events per rolling minute across all its
streams, 600 by default; past that a webhook is answered 429.
Subscriptions take events out. Each subscription has a filter of event
kinds and exact field values, for example
{"kinds": ["issues"], "fields": {"body.action": "opened"}}. A kind matches
by dotted prefix, so issues also matches issues.opened. An empty filter
matches every event. A subscription starts at the end of its stream: an event
received before the subscription was created is skipped with the reason
“received before the subscription started”, even when it is redelivered later.
Each subscription reacts to an event at most once, and the reaction is recorded
as reacted, skipped with a reason, or error.
- Trigger. A trigger with
trigger_type: "stream"names astream_idand anevent_filter, and runs its agent for each matching event that passes its conditions. The task’s id is derived from the subscription and the event, so a redelivery never starts a second task. Withsession({"continue": true, "idle_timeout": "30m"}), the next event of the samesession_keyjoins the running task instead of starting a new one. Withbatch({"window": "1h", "max_events": 50}, either may be left out), the trigger runs its agent once for the events of a batch: the first event opens it, and it fires when the window has passed or it holdsmax_events, whichever comes first, never aboveAGENTAREA_TRIGGER_BATCH_MAX_EVENTS(100 by default). Each event meets the conditions and the sender check before it joins, and its reaction is recorded asbatcheduntil the batch fires; then every event in it isreactedwith the one task, which gets them all underevents. Switching the trigger off or deleting it closes its open batches: their events are recorded asskippedand no task starts. - Forward.
POST /v1/workspaces/{workspace}/streams/{stream_id}/forwardscopies matching events into one or more other streams, never into its own input, and you must be able to edit every output. A copy keeps the original’s source, sender and session, points itscausation_idat the original, and is one step deeper. A copy that would be deeper thanAGENTAREA_EVENT_FORWARD_DEPTH(8 by default) is not written, and the forward’s reaction is recorded as an error with the depth as the reason. - External MCP Events subscriber. The AgentArea MCP server offers each
stream you can read as an event type named
<workspace>/<stream id>. An MCP client outside AgentArea reads it withevents/pollfrom a cursor, or callsevents/subscribeto receive signed webhooks at anhttpsURL, narrowed by kind prefix, source type or session key. A subscription lasts 1 hour by default (1 minute to 24 hours), is renewed by subscribing again, and a workspace holds at most 100. A failed delivery is retried after 30 s, 2 min, 10 min, 30 min, 1 h and 2 h; after the last retry the subscription is marked failed. See Subscribe to a stream over MCP Events. - Processor (in progress). Python an agent writes,
def process(event), that the platform runs in the sandbox once per matching event. The events it returns are written into its declared output streams, linked to the event it read. The code gets no secrets and every reader of the stream can see it. See Transform a stream with a processor. - Batch window (in progress). A stream trigger with
"batch": {"window": "1h", "max_events": 50}fires once for a batch of events instead of once per event. The batch opens with its first event and fires when the window has passed ormax_eventshave joined, whichever comes first. A batch never holds more thanAGENTAREA_TRIGGER_BATCH_MAX_EVENTSevents, 100 by default.
platform, created the first time the platform has an event for it, and
written only by the platform. It carries task.completed, task.failed,
task.cancelled, approval.requested and input.request events. Each body
is a summary: the task and agent ids, the status, the result or error cut to
500 characters with secrets masked, and the cost. Tool arguments, tool output
and error details stay in the task. Members can read the stream and put
triggers on it. Nobody can delete it, add a source to it or forward into it;
each of those is refused with 409. A trigger never reacts to an event that
comes from a task it started, and a firing deeper than
AGENTAREA_EVENT_FORWARD_DEPTH is skipped. A trigger on task.failed that
runs an on-call agent therefore does not wake itself.
The events feed shows what happened to each event. The Events page,
and GET /v1/workspaces/{workspace}/streams/events, list the events of every
stream you can read, newest first. They filter by stream, source type, kind
(order.* for a prefix), sender, session, result and time. While the page is
open it updates live from /v1/workspaces/{workspace}/streams/events/live.
Each event carries a processing status:
An event’s detail lists each subscription that handled it, with its verdict,
the reason, and the task it started with that task’s current status. Agents
read the same feed with the
streams_list_events tool, and one stream from a
cursor with read_stream from the agentarea/stream_events toolset, which
hands event data over under a notice that it is data, not instructions.
Retention is one setting for the deployment. The feed keeps events by day.
A day older than AGENTAREA_EVENT_RETENTION (7 days by default) is dropped
whole, for every stream and workspace at once; a stream has no retention of its
own. With AGENTAREA_EVENT_ARCHIVE on, each day is first written to the object
store as gzipped JSONL, one object per workspace. An MCP Events poll from a
cursor older than the retention is answered truncated. How events move
between intake, the router and the feed, and what the broker keeps, is
described in The event bus.
Why not one webhook per consumer
Wiring a webhook to the one trigger it starts has fewer parts: no stream, no router, no recorded reactions. It is where AgentArea started. It stops working once a second consumer is legitimate, because the only way to add one is a second registration with the provider. A stream takes each delivery once and hands it to any number of subscriptions, each recorded on its own. The cost is a hop. A webhook is answered before anything has reacted to it, so the sender’s202 says the event was recorded, not that an agent ran. To know
what happened you read the event’s processing status. The shared envelope has
a cost too: it names only what every provider can be read for. Anything else
stays in the body, where an agent reads it or a filter matches it as body.*.
Limits
- Read access is per stream. Whoever can read a stream sees every event in it, including events their own subscriptions would never match.
- The write quota is per workspace. One noisy source can use up the minute’s budget for every other stream in the workspace.
- An event without a key is never a repeat. When neither the request nor the entry names a delivery id, each retry from the sender is a new event and can start a new task.
- Intake recognizes a repeat for 24 hours. A repeat that arrives later is recorded in the feed a second time. A subscription that already reacted to the event does not react again.
- Retention is not per stream. A stream that needs a longer history needs a
longer
AGENTAREA_EVENT_RETENTIONfor the whole deployment, or the archive. - Files outlive their events. Attachments and large bodies stay in the workspace’s files after the event’s day is dropped, and the archive is not readable through the API.
- The platform stream carries task outcomes only. No other platform activity is written to it.
- Some MCP servers cannot be event sources. A server instance that authenticates through an auth config, or one the platform manages, is refused when the source is created.
- An MCP Events webhook does not replay. A subscriber that missed events
reads them with
events/pollfrom its cursor, within the retention. - Processors and batch windows are in progress. Their behaviour on this page can change before release.
Related
The event bus
Topics, consumer groups and what each one guarantees.
Collect events into a stream
Add a webhook or poll source to a stream.
Subscribe over MCP Events
Poll a stream or receive signed webhooks from outside.
Transform a stream with a processor
Have an agent write code that turns events into new ones.
Task events
The feed one running task emits, which a stream is not.