Notifications

The Notifications API decides who hears about events like a failed deploy or an expiring SSL cert, and how. You register channels (where alerts go — email, webhook, Slack, Discord, Microsoft Teams, or the in-app bell), toggle subscriptions (which event categories reach each channel), set org-wide defaults for new members, and read deliveries (the alert feed behind the bell icon). In the dashboard this is the Settings → Notifications page. Channels, subscriptions, and deliveries are per-user; defaults are per-org.

Categories

Categories are the stable, user-facing event groups (e.g. deploy.failed, backup.failed, domain.expiring) that subscriptions and defaults key off. They live in code, not the database, so GET /api/notifications/categories is a static registry — each entry has an id, group, label, description, and defaultEnabled.

The response also carries a groups array ({ id, label }, already in display order) that the categories' group field points into — deployment, app_health, backups, jobs, domains, members, billing. The billing group and its categories are omitted outside Openship Cloud, where nothing can fire them.

const result = await ship.notifications.categories();
console.log(result);

curl "$OPENSHIP_URL/api/notifications/categories" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Create a channel

A channel is a destination. The config object is shape-checked per kind; secrets in it (webhook signing keys, Slack URLs, Telegram bot tokens) are stored encrypted and never returned in full.

const result = await ship.notifications.createChannel({
  kind: "email",
  label: "On-call inbox",
  config: {
    address: "ops@example.com",
  },
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/notifications/channels" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"email","label":"On-call inbox","config":{"address":"ops@example.com"}}'

The config shape depends on kind:

New channels start enabled: true. An in_app channel is verified immediately; every other kind starts unverified and must be verified (via a test send) before it will deliver — flip verified with PATCH.

Update a channel

Send only the fields you want to change. Changing config on a non-in_app channel resets verified to false, since the destination may have moved.

PATCH /api/notifications/channels/:id

Subscribe a channel to a category

A subscription is one toggle in the (user, org, category, channel) grid. PUT is an idempotent upsert — send the same triple again to flip enabled. The channelId must be a channel you own.

const result = await ship.notifications.upsertSubscription({
  category: "deploy.failed",
  channelId: "chan_123",
  enabled: true,
});
console.log(result);

curl -X PUT "$OPENSHIP_URL/api/notifications/subscriptions" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category":"deploy.failed","channelId":"chan_123","enabled":true}'

Org defaults

Defaults seed the subscription grid for new members of the org. Setting a default is admin-only (notifications:admin); reading them is not.

PUT /api/notifications/defaults

Read the alert feed

GET /api/notifications/deliveries returns your recent deliveries in the active org — this is the history behind the bell icon. GET /api/notifications/deliveries/unseen-count powers the badge, and POST /api/notifications/deliveries/:id/seen clears one.

const result = await ship.notifications.listDeliveries({
  unseen: true,
  limit: 20,
});
console.log(result);

curl "$OPENSHIP_URL/api/notifications/deliveries?unseen=true&limit=20" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Errors

Operations