Skip to main content
Issue events announce what happens to issues in a project: an issue was created, changed in a way Sazabi announces, resolved, ignored, or reopened. A client connected to the Sazabi MCP server can read them three ways: polling, holding a stream open, and receiving signed webhook deliveries. Issue events are an extension served beside the MCP protocol, not part of it. The protocol revision decides how a request is framed and negotiated; the extension decides whether the server offers events at all. A client that does not ask for events loses nothing: tools, authentication, and errors behave the same. Issue events are enabled per project. In a project without them, events/list still names the events, and a poll, a stream, or a subscription is refused.

Discovery

The server advertises issue events in its discovery result. On revision 2026-07-28, server/discover lists the extension under capabilities.extensions with no settings to configure:
events/list then names every event, with a short description and the JSON Schema for its arguments and for its payload. It describes the webhook profile, so each event’s delivery is ["webhook"]; polling and streaming read the same events:
events/list answers on every protocol revision the server speaks. Polling and streaming need revision 2026-07-28; the initialize handshake revisions carry the webhook methods only, and initialize names no events capability.

Event types

Every event carries the same bounded summary, frozen when Sazabi recorded it:
The summary never carries the agent prompt or the report. Read those with the issue-reading tools.

Polling

events/poll answers one bounded page per request and keeps no server-side state, so the client owns the cursor and stopping polling ends the watch. There is no subscription to create and nothing to unsubscribe. Send the request on revision 2026-07-28, with the standard Mcp-Method and Mcp-Name headers. Mcp-Name must name the same event as params.name:
The answer holds the events oldest first, the cursor to send next, and how long to wait before asking again:
A page returns at most 100 events, 50 unless maxEvents asks for another count. hasMore says another page is ready now; nextPollMs says how long to wait when it is not.

Pushing over a held-open stream

events/stream takes the same params as a poll without maxEvents, and answers with a text/event-stream response the server keeps open. The first journal read decides admission: anything refused before that point is an ordinary JSON-RPC error and no stream opens. Frames are JSON-RPC notifications, each carrying the request id as _meta["io.modelcontextprotocol/subscriptionId"]: A stream ends normally when its 30 minutes are up, when the OAuth token that opened it expires, or when the server drains for a deploy. The final result is empty, so a client reconnects from the last cursor it saw rather than treating the end as a failure. events/stream holds one subscription per request. Frames are delivered at least once, so deduplicate on eventId.

Webhook deliveries

events/list, events/subscribe, and events/unsubscribe deliver events to an HTTPS callback you control. Webhooks replay nothing: delivery starts with the next event after the subscription activates. Only a signed-in person can subscribe, so this is the one mode a secret key cannot use. A project-scoped credential contributes its project; arguments carry the filters.
The secret is a Standard Webhooks signing secret: whsec_ followed by your base64-encoded key, which must decode to 24 to 64 bytes. The answer names the subscription and the time to refresh it by:
Subscribing again with the same project, event, filters, and URL refreshes the same subscription, and the id stays the same. A subscription lasts at most seven days and at least one hour; refresh before refreshBefore to keep it. events/unsubscribe ends it and stops its queued deliveries, and answers the same whether or not the subscription existed.

Verifying the callback

Nothing is stored or activated until your endpoint accepts a signed challenge. The server sends a POST whose body is:
Answer with a 2xx and a JSON body naming the same challenge. An endpoint that fails the challenge is not activated. The URL must be HTTPS; redirects are refused and the addresses it resolves to must be public.

Signed deliveries

Each delivery is one JSON POST with these headers: The body is the event with cursor fixed at null:
A delivery is at most 256 KiB and its callback has 10 seconds to answer. A 2xx acknowledges it; 410 and 413 end that delivery without a retry; other failures retry, up to eight attempts, with the same bytes and a fresh timestamp and signature. Because an attempt can land twice, deduplicate on eventId.

Authentication and project scope

The server accepts the same credentials here as for tools: an OAuth sign-in, or a secret key in the X-Sazabi-Secret-Key header. Reads and streams accept both; webhook subscriptions accept only a signed-in person. A project is chosen by projectId in arguments. A project-scoped secret key that omits it reads its own project; naming another project is refused. Filters narrow the events by severities, componentIds, and types. Every read is authorized as an ordinary issue read for the caller at that moment, so events follow issue visibility rather than notification settings: a person who loses access to a project stops receiving its events on their next read, and an event is never delivered on cached authority.

Cursors, replay, and gaps

A cursor is an opaque position, never a credential: it is bound to the organization, project, event, and filters that produced it.
  • First read. A cursor that is null or absent starts at the newest event and returns no history.
  • Progress. Every answer advances the cursor, including a read that returns nothing, so a quiet stream or a poll that found nothing still moves forward.
  • Replay. A stream reconnects from the last cursor it saw and replays what happened since. Replay is at least once.
  • Gaps. Events are retained for seven days per project, up to 10,000 events. A cursor older than that is past retention, and the answer (or the notifications/events/active frame) sets truncated: true and resumes from the oldest event still retained. Some events were missed; nothing replays them.
  • Webhooks. Deliveries never replay history. The subscription’s cursor is null when it is created.

Without promising more

Each mode delivers the same events. What each one does not do: None of the modes promise exhaustive issue history or exactly-once execution of anything your agent does in response. None of them grant access: every read, page, and reconnect is authorized again.

Errors

Further reading

MCP server

The protocol reference, authentication, and tool surfaces.

Issues

What issues are and how the agent works them.