Notifications

Notifications surface important SOIT events to users and operators. They are useful for approval requests, failed runs, long-running task updates, governance events, and operational alerts.

When to use notifications

Use notifications when a person needs to react to a runtime or governance event without continuously watching an observe page. Typical triggers:

• An agent or workflow run needs human approval before a governed action proceeds.
• A run or task failed and someone owns the follow-up.
• A long-running task (large ingestion, batch evaluation) reached a milestone or finished.
• A governance event occurred — a publish, a rollback, a policy denial worth human attention.

How notifications work

• Runtime events produce notification records through the same outbox-backed dispatch as other side effects — a committed event is never silently dropped.
• Notification records preserve workspace and identity scope: users see notifications for their workspaces only.
• Each notification links back to the relevant run, task, workflow, or capability, so the path from "something needs attention" to the full evidence is one click.
• Delivery state is tracked per notification, making missed or unread operational events auditable.

How notifications connect

• Approval requests notify their approvers when opened, the new approver when delegated, and their requester when they expire, in the task category.
• Failure paths in Tasks and Runs notify responsible users.
• Governance events from Versioning and Secrets and Security can surface as notifications.
• The notification feed complements Observe: Observe is where you investigate; notifications are how you learn something needs investigating.

API and UI surfaces

• API prefix: /api/v1/notifications
• Web route: /notifications