Notifications

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Orqestra turns committed governance facts — execution outcomes, approvals, incidents, compliance findings, connector health, credential expiry, and policy configuration changes — into per-recipient notifications. Recipients read them in the portal inbox and choose how they are delivered. Administrators configure shared external destinations and per-role defaults, and review delivery health and the suppressed-decision audit trail.

The owner decision is user-choice-first: no category or channel is mandatory, including the in-portal channel. When a recipient opts out of a governance-relevant category, the system records a durable suppressed-decision audit record instead of forcing delivery.

Concepts

Turning notifications on for a tenant

Notifications are a per-organization setting, on by default; the advanced tier (digests, batching, personal chat, announcements, and project and environment overrides) is a second setting, off by default. A namespace administrator changes both in Administer › Access & org › Tenant settings (or with orqestractl namespace settings set); the change applies to the next request, with no redeploy. When a setting is off, all six notification pages show “disabled for this tenant” and the API answers 403 enterprise_capability_required naming the setting; queued deliveries for an off tenant are suppressed rather than sent, and turning it back on does not replay them.

Inbox and preferences

Every workspace member can read their inbox and manage their own preferences.

The inbox lists notifications routed to the recipient in the active workspace, filterable by status, and each row can be marked read, unread, or archived. The preference center is a category-by-channel matrix at four scopes: a global tab that applies across every workspace, a workspace tab whose overrides win over the global defaults, a project tab narrowing an override to one workload, and an environment tab narrowing it further to one workload in one deployment environment. Each cell is tri-state — inherit, on, or off. Because preferences are upserted per entry and never deleted, an explicit on/off choice can be flipped but no longer returns to inherited, and an explicit opt-out is never silently re-enabled.

The project and environment tabs pick a workload (and, for environment, an environment from the workspace’s registered environments) before the matrix mounts. An Effective tab explains, for a chosen category and context, which channels a notification would actually use and which override level decided each.

Precedence, deepest first — a deeper scope wins: global < workspace < project < environment, then the admin default profile for the recipient’s role, then a small built-in fallback. User choice always wins over the admin default.

The project and environment override levels are an Enterprise capability (notifications-advanced, a Tenant settings switch); when it is not enabled those tabs render a locked state and their routes return 403. The Effective explainer itself is not gated (its workload/category context always works), though its environment-context picker reads the Enterprise environments list. The SDK exposes get/set_project_preferences, get/set_environment_preferences, list_environments, and get_effective_preferences; the CLI adds --scope project|environment (with --workload/--environment), notifications environments list, and notifications preferences effective.

Permissions

SDK

from orqestra_sdk import OrqestraClient
 
async with OrqestraClient(
    "http://localhost:8000", workspace_id="workspace-123"
) as client:
    unread = await client.notifications.list_inbox("workspace-123", status="unread")
    if unread:
        await client.notifications.update_inbox_status(
            "workspace-123", unread[0]["notification_id"], status="read"
        )
 
    await client.notifications.set_workspace_preferences(
        "workspace-123",
        [{"category": "incidents", "channel": "email", "enabled": True}],
    )

CLI

orqestractl notifications inbox list --status unread
orqestractl notifications inbox set-status <notification-id> --status archived
orqestractl notifications preferences list --scope workspace
orqestractl notifications preferences set --scope workspace --file prefs.json

prefs.json is a JSON array of { "category", "channel", "enabled" } entries.

Shared destinations and defaults

Administrators manage the external delivery endpoints and the per-role defaults. Destinations and default profiles exist at two scopes: a workspace scope owned by that workspace’s admins, and an organization scope owned by organization admins for shared, org-wide routing.

A destination stores non-secret channel configuration and an indirect secret_ref pointer to a credential held in the configured secret backend. The credential value itself is never sent to or returned by the notifications API: the read surface exposes only a has_secret_ref flag, and any sensitive key in the configuration is redacted to [redacted] on ingest. Saving a destination stores configuration; it does not validate the credential or reachability — allowlist and request-forgery checks run at delivery time.

Permissions

Create a destination over the HTTP API

curl -X POST \
  "http://localhost:8000/v1/notifications/workspaces/workspace-123/destinations" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "pagerduty",
    "display_name": "On-call",
    "redacted_metadata": {},
    "secret_ref": "vault:notifications/oncall-routing-key",
    "is_enabled": true
  }'

The same operations are available through the SDK (client.notifications.create_workspace_destination, create_organization_destination, and their list/update/delete counterparts) and the CLI:

orqestractl notifications destinations create \
  --scope workspace --type slack --name "Eng alerts" \
  --metadata '{"url": "https://hooks.example.com/services/..."}'
orqestractl notifications destinations list --scope organization --organization <org-id>
orqestractl notifications defaults set --scope workspace --file defaults.json

defaults.json is a JSON array of { "profile_ref", "category", "channel", "enabled" } entries, where profile_ref is the recipient’s role.

Delivery health and suppressed-decision audit

Operators and admins can review the delivery outbox and the suppressed-decision audit trail.

Delivery health lists one row per delivery attempt with its status (pending, claimed, sent, failed, suppressed, or cancelled), attempt count, next-retry time, and last error. The suppressed-decision view lists the durable records written when a governance-relevant notification was not delivered because the recipient opted out, keyed by recipient, category, source event, and reason code.

Permissions

Audit and redaction

• Destination create and update record the configuration key names and the has_secret_ref flag in the governance audit chain — never the secret value or sensitive configuration values. Destination delete records the destination id.
• Suppressed-decision records are durable audit rows; they are read-only and reconcile to the source event’s retention class.
• The delivery-health payload returned by the API is already redacted.

Failure Modes

See Also

For the delivery-worker runbook semantics — retries, backoff, circuit breaking, destination health, and the audit contract — see the operator reference for notification delivery in docs/reference/notification-delivery.md.