Notifications

Notifications tell the people in a workspace when something needs their attention: a client submitted files, a scheduled revision went live, a background job failed. Each person controls their own notifications, so a designer can get every submission by email while an admin only sees failures in the dashboard. This guide explains the events, how delivery works, and how to change your preferences.

Notifications are personal. They belong to a signed-in user, not to the workspace or an API key, which is why API keys cannot read or change them. For machine-to-machine events, use workspace webhooks instead.

Events#

Every member of the workspace receives each event, whatever their role, filtered by their own preferences. The same event is never delivered to the same person twice.

How delivery works#

Each enabled event creates an entry in your Inbox, with a title, a short description, and a link to the file, request, or page involved. In addition, each event can go out through these channels:

And each event has a timing mode:

• immediate: email and webhook deliveries are queued as soon as the event happens.
• digest: email and webhook deliveries are held until 17:00 UTC on the day of the event. An event that happens after 17:00 UTC goes out on the next worker run instead of waiting for the next day. Each notification is still sent as its own message; they are not combined into one email.

The inbox entry is always created immediately, whichever mode you choose.

Delivery allowance#

Email and webhook deliveries count against the workspace's monthly notification allowance. Inbox entries do not.

When the allowance runs out, email and webhook deliveries are skipped without an error until the next billing period. Inbox entries keep arriving, so nobody misses an event entirely.

Change your preferences#

Open Notifications at the bottom of the dashboard sidebar and switch to Preferences. Events are grouped into Files & collaboration and Workspace health. Each row shows the event's current channels as badges and a switch to turn it on or off. Turning an event off stops both the inbox entry and any email for it. Each change saves immediately and applies only to you, in the current workspace.

Channels and the timing mode are set through the preferences API described below.

Defaults and personal overrides#

Until you change an event, it uses the workspace default for that event, or, when the workspace has none, the built-in default: enabled, in-app only, immediate. The first time you save a preference for an event, SteadyLink stores a personal override for that one event; other events keep following the defaults. There is no reset action, so to go back to the default behavior, save the default values.

Use the preferences API#

These routes require a signed-in user session (Authorization: Bearer with your session token) and act on the active workspace. An API key gets 403 with "User preferences require a user session" on reads and 422 on writes.

curl https://api.steadylink.io/api/notifications/preferences \
  -H "Authorization: Bearer $STEADYLINK_SESSION_TOKEN" \
  -H "X-Workspace-Id: 2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b"

{
  "events": ["asset.replaced", "asset.rolled_back", "bandwidth.unusual", "job.failed", "link.expiring", "request.submitted", "schedule.published", "traffic.unusual"],
  "channels": ["email", "in_app", "webhook"],
  "items": [
    { "eventType": "asset.replaced", "channels": ["in_app"], "mode": "immediate", "enabled": true, "inherited": false },
    { "eventType": "request.submitted", "channels": ["email", "in_app"], "mode": "immediate", "enabled": true, "inherited": false }
  ]
}

Each item is the effective preference for one event. inherited is true when the value comes from a workspace default rather than your own override or the built-in default.

To change an event, send the complete preference for it:

curl -X PUT https://api.steadylink.io/api/notifications/preferences \
  -H "Authorization: Bearer $STEADYLINK_SESSION_TOKEN" \
  -H "X-Workspace-Id: 2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "request.submitted",
    "channels": ["in_app", "email"],
    "mode": "digest",
    "enabled": true
  }'

{ "eventType": "request.submitted", "channels": ["email", "in_app"], "mode": "digest", "enabled": true }

Fields you leave out are not kept from the previous value: channels falls back to ["in_app"], mode to immediate, and enabled to true. Always send all four. The request is rejected with 422 "Invalid notification preference" when eventType is unknown, channels is empty or contains anything other than in_app, email, and webhook, or mode is not immediate or digest.

Read the inbox and delivery log#

• Inbox (GET /api/notifications): your latest 100 notifications in the workspace and an unread count, which also drives the badge on the sidebar. Mark one read with POST /api/notifications/{notification_id}/read, or use Mark all read in the dashboard.
• Delivery log (GET /api/notifications/deliveries, or the Delivery log tab): your latest 100 email and webhook deliveries, each with its channel, status (queued, delivered, or permanent_failure), attempts, lastError, and deliveredAt. Export CSV downloads the log. Check it when an email you expected did not arrive: a queued entry in digest mode is waiting for 17:00 UTC, and a permanent_failure shows why it gave up.

Notification messages contain titles, short descriptions, and links into the dashboard, never file contents or signed download links. Opening the link still requires access to the workspace.

Next steps#