Hoody 通知通过 HTTP 发送桌面通知。
通过单次 HTTP POST 向任意容器显示器发送 Linux 桌面通知。通知服务器在容器的 X11 显示器上调用 notify-send——触发、获取历史记录或实时流式传输。
# 向显示器 0 发送通知
curl -X POST "https://abc123-def456-n-1.node-us-1.containers.hoody.com/api/v1/notifications/notify"
-d '{"display":"0","summary":"Build Complete","urgency":"normal"}'
# 响应
{"success":true}
三个步骤，每步一次 HTTP 调用。
每条通知遵循相同的生命周期：触发、获取历史或实时流式传输、完成后关闭。
触发
POST /notify 向目标 X11 显示器发送 notify-send 调用。提供 display、summary，以及可选的 urgency、body、expire_time 或 icon。
# Fire a notification
curl -X POST .../notify
{"display":"0",
"summary":"Build Complete",
"urgency":"normal"}
{"success":true}
投递
notify-send 把通知交给目标 X11 显示上的系统通知守护进程。它会出现在任何已连接的 display 会话里，并按 urgency 和 expire_time 自动过期。
# notify-send on display :0
notify-send → X11 :0
▸ Build Complete
normal · auto-expires
获取或流式传输
GET /[display] 获取通知历史，支持可选的 limit、since、username 和 session 筛选。通过 WebSocket 连接 /stream?displays=0 可获取实时推送更新。
# Poll history
curl .../0?limit=50
# Or stream live
new WebSocket(
"wss://.../stream?displays=0"
)
low、normal、critical。
三个紧急程度级别直接映射到 notify-send 行为。选择合适的级别，通知守护进程负责其余处理。
快速消失。将 expire_time 设为 3000，适用于后台任务、遥测或不应打断专注的信息性提示。
"urgency": "low",
"expire_time": 3000
标准级别。省略 urgency 时的默认值。通知守护进程在配置的超时后显示并自动关闭。
"urgency": "normal"
// 默认值 —— 省略即使用此项
持久显示——需要手动关闭。将 expire_time 设为 0，适用于系统故障、构建错误或任何需要立即处理的情况。
"urgency": "critical",
"expire_time": 0
获取历史或实时流式传输。
两个读取频道满足不同需求：REST 用于审计日志和一次性查询，WebSocket 用于仪表盘和实时监控。
获取某个显示器的通知历史，支持按 limit、since 时间戳、username 或 session ID 筛选。适用于审计日志、一次性查询和批量处理。
# 获取 display 0 的最近 50 条
curl ".../0?limit=50"
# 按时间过滤
curl ".../0?since=1749025000000"
包含 id、summary、urgency、timestamp 和 icon_url 的通知对象 JSON 数组。
使用 displays=0,:1,2 或 displays=all 订阅一个或多个显示器。消息到达时实时推送。适用于仪表盘和实时监控。
# 打开一个 WebSocket
const ws = new WebSocket(
"wss://.../stream?displays=0"
)
# 收到消息时
ws.onmessage = (e) => {
const msg = JSON.parse(e.data)
// msg.summary, msg.body, msg.urgency
}
每条新通知到达时推送 [ type: "notification", data: [ id, summary, urgency, timestamp ] ]。
从构建流水线到 ML 任务。
任何长时间运行的进程需要发出完成或失败信号时，一次 HTTP POST 即可搞定。
CI/CD 告警
长时间构建完成后，HTTP POST 在容器显示器上触发通知——在任意活跃的显示器会话中可见。
系统监控
服务器告警路由到容器 X11 显示器上的桌面通知，在任意活跃的显示器会话中可见。
长时间运行的任务
数据导出、视频渲染、ML 模型训练、备份完成——完成时通知，无需轮询。
自动化工作流
Cron 作业、定时任务和自动化脚本在完成或失败时通知容器显示器。
8 个端点。一个通知服务器。
创建主题和订阅者、触发推送通知、流式传输事件并检索交付历史——全部通过简单 HTTP。
Base URL https://abc123-def456-n-1.node-us-1.containers.hoody.com
触发
1 个端点POST .../api/v1/notifications/notify
拉取与流式
2 个端点GET .../api/v1/notifications/{display}?limit=50
图标
1 个端点GET .../api/v1/notifications/icons/{iconId}
Health & Metrics
1 个端点GET .../api/v1/notifications/health