Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Notification Server

Section titled “Notification Server”

The Hoody Notification Server is a lightweight kit service that delivers desktop notifications to a target display by invoking notify-send on the underlying system. It is the recommended way for Hoody kits and integrations to surface short, transient messages to a user at a specific display without requiring a separate notification UI.

This page describes the surface area of the notification-server kit: triggering a desktop notification, reading recent notification history for a display, dismissing notifications, subscribing to a real-time stream of notification updates, fetching notification icon images, and basic health and metrics endpoints.

When to use it

Section titled “When to use it”

Use the Notification Server when a Hoody component needs to:

  • Show a transient desktop notification (title, body, optional urgency, icon, and timeout) on a specific display.
  • Inspect recent notifications that have been delivered to a display, including which ones the user has dismissed.
  • Dismiss a notification or clear the dismissed flag on a previously delivered notification.
  • Subscribe to a live stream of notification activity for a display, useful for building mirror UIs or test harnesses.
  • Resolve a notification icon id to its image asset.
  • Probe liveness and scrape Prometheus-style metrics from the service.

What it does not provide

Section titled “What it does not provide”

The Notification Server is intentionally narrow in scope. It is not a multi-channel notification platform. Specifically, it does not provide:

  • Email, in-app, push, SMS, or webhook delivery channels.
  • Notification templates, localization, or rendering rules.
  • User preferences, quiet hours, opt-out, or per-user priority filtering.
  • Per-notification delivery-status tracking (no pending/delivered/failed states), retry, or backoff configuration. The only documented failure semantics are rate limits: 60 requests/minute general, 10 requests/minute on the notify endpoint, and 100 requests/minute on the icon endpoint.
  • Acknowledgment callbacks or read receipts.

If you need any of the above, use a dedicated messaging or notification platform rather than this kit.

Service shape at a glance

Section titled “Service shape at a glance”

The endpoints exposed by this kit fall into a handful of small groups:

  • Trigger: POST /api/v1/notifications/notify — synchronously invokes notify-send on the target display and records the notification in history.
  • History: GET /api/v1/notifications/{display} — returns historical notifications for a display, including their dismiss state.
  • Dismiss state: POST /api/v1/notifications/dismiss and DELETE /api/v1/notifications/dismiss — mark a notification as dismissed, or clear the dismissed flag.
  • Streaming: GET /api/v1/notifications/stream — Server-Sent Events stream of notification updates.
  • Icons: GET /api/v1/notifications/icons/{iconId} — serve a notification icon image.
  • Operations: GET /api/v1/notifications/health and GET /api/v1/notifications/metrics — liveness probe and metrics scrape.

Each of these operations is documented in the child pages of this section. Refer to them for parameter, request body, response, and SDK details.