title: Notifications description: Notification center behavior and APIs

Notifications

SwarmClaw includes a real-time Notification Center in the sidebar/mobile header.

Notification Center UX

  • Live updates via WebSocket invalidation
  • Unread badge counter
  • Mark-all-read
  • Clear-read notifications
  • Optional action link per notification (for example: open docs or external support links)
  • Operational alerts for automatic safety actions (for example: plugin auto-disabled after repeated failures)

Notification Schema

Each notification includes:

  • id
  • type (info, success, warning, error)
  • title
  • message (optional)
  • actionLabel (optional)
  • actionUrl (optional)
  • read
  • createdAt
  • entityType (optional, example: plugin)
  • entityId (optional)
  • dedupKey (optional)

API

  • GET /api/notifications?unreadOnly=true&limit=100
  • POST /api/notifications
  • DELETE /api/notifications (clear read notifications)
  • PUT /api/notifications/:id (mark read)
  • DELETE /api/notifications/:id

Outbound Webhook Alerts

Notifications can be forwarded to an external webhook for ops alerting. Configure in Settings:

  • alertWebhookUrl — Destination URL (Discord webhook, Slack incoming webhook, or any HTTP endpoint)
  • alertWebhookType — discord, slack, or custom (controls payload format)
  • alertWebhookEvents — Which notification types to forward: error, warning (default: ['error'])

Alerts are rate-limited (60s dedup window per notification key) and best-effort (5s timeout, failures are logged but don't block).

CLI Examples

swarmclaw notifications list --query unreadOnly=true
swarmclaw notifications create --data '{"type":"info","title":"Release ready","message":"Tag vX.Y.Z to publish","actionLabel":"Open Release Guide","actionUrl":"https://github.com/swarmclawai/swarmclaw/releases"}'
swarmclaw notifications mark-read <notificationId>
swarmclaw notifications clear