Events reference

HowlOps events are emitted in three delivery channels:

1. Webhook: HTTP POST to your endpoint (Webhooks reference)
2. WebSocket: WSS /api/v1/ws real-time stream
3. In-app notification feed: /api/v1/notifications/feed

Webhook events

Outbound webhook deliveries use the stable monitor.* namespace. See the Webhooks reference for the full payload shape.

Heartbeat-sourced events reuse the same monitor.down / monitor.up event names; the payload carries heartbeat_id (with monitor_id empty) to distinguish them.

WebSocket events

Connect to WSS /api/v1/ws?token=<workspace_api_token>. The token must be a workspace API token (howlops_<hex>), not an OAuth or JWT token. Each message is a JSON object with channel, type, and data fields.

The channel field is the routing key clients use to subscribe to specific event streams. Frames without a channel are still delivered but the frontend drops them unless listening for all frames.

incident.created

{
  "channel": "monitors.status",
  "type": "incident.created",
  "data": {
    "incident_id": "uuid",
    "monitor_id": "uuid",
    "status": "open",
    "severity": "critical | warning | info"
  }
}

incident.acknowledged

{
  "channel": "monitors.status",
  "type": "incident.acknowledged",
  "data": {
    "incident_id": "uuid",
    "monitor_id": "uuid"
  }
}

incident.resolved

{
  "channel": "monitors.status",
  "type": "incident.resolved",
  "data": {
    "incident_id": "uuid",
    "monitor_id": "uuid"
  }
}

incident.assigned

{
  "channel": "monitors.status",
  "type": "incident.assigned",
  "data": {
    "incident_id": "uuid",
    "monitor_id": "uuid"
  }
}

monitor.status_changed

{
  "channel": "monitors.status",
  "type": "monitor.status_changed",
  "data": {
    "monitor_id": "uuid",
    "status": "up | down | paused",
    "response_time_ms": 142,
    "checked_at": "ISO 8601"
  }
}

heartbeat.ping_received

{
  "channel": "heartbeats.status",
  "type": "heartbeat.ping_received",
  "data": {
    "heartbeat_id": "uuid",
    "status": "up | missed",
    "last_ping_at": "ISO 8601 | null"
  }
}

Keep-alive ping

There is no application-level tick JSON event. To keep the connection alive, the server sends a WebSocket protocol PING control frame every 30 seconds to each connected client. Browsers and standard WebSocket libraries answer these PING frames automatically, so no application-level pong or handling is required.

In-app notification feed events

Returned by GET /api/v1/notifications/feed (paginated). Real-time updates are pushed on the notifications.feed WebSocket channel.

The type field identifies the event kind. The documented values correspond to the categories recognized by the feed:

Feed item shape:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "user_id": "uuid",
  "type": "down",
  "title": "Production API is down",
  "body": "Monitor detected failure at 10:00 UTC",
  "severity": "critical",
  "incident_id": "uuid",
  "monitor_id": "uuid",
  "category": "incident",
  "reactions": [],
  "read_at": null,
  "created_at": "ISO 8601"
}

Note: read_at is null when unread and an ISO 8601 timestamp when read. There is no boolean read field. There is no link field; callers construct the deep link from incident_id or monitor_id.

Severity levels

See also

• Webhooks reference
• REST API reference