Notifications API

Base path: /api/v1/notifications

Implementation reference: internal/notifications/ (handler, service, models, channels).

Note: Notification endpoints are registered under /api/v1 but the corresponding HTTP handlers are not yet wired into the router in cmd/slozy-web/main.go. The notification service (internal/notifications/service.go) supports email, Slack, and webhook delivery channels.

Endpoints

Method	Path	Description	Auth Required
GET	/notifications/history	List notification history	Yes
GET	/notifications/channels	List configured notification channels	Yes
POST	/notifications/rules	Create a notification rule	Yes
POST	/notifications/test	Send a test notification	Yes

---

GET /notifications/history

Returns a paginated list of sent notifications, optionally filtered by SLO.

Query Parameters:

Parameter	Type	Default	Description
slo_id	int	—	Filter by SLO ID
page	int	1	Page number
page_size	int	10	Items per page

Response (200 OK):

{
  "notifications": [
    {
      "id": 123,
      "slo_id": 1,
      "rule_id": null,
      "channel_id": 1,
      "status": "delivered",
      "alert_type": "violation",
      "priority": "high",
      "subject": "SLO Violation Alert",
      "message": "API response time exceeded threshold of 99.95%",
      "sent_at": "2026-06-09T14:30:00Z",
      "delivered_at": "2026-06-09T14:30:05Z",
      "retry_count": 0,
      "max_retries": 3,
      "error_message": "",
      "metadata": {},
      "created_at": "2026-06-09T14:30:00Z",
      "updated_at": "2026-06-09T14:30:05Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10,
  "has_next": false
}

Notification status values: pending, sending, sent, failed, delivered.

Alert type values: violation, warning, recovery, manual.

Priority values: low, medium, high, critical.

---

GET /notifications/channels

Lists all configured notification channels for the user's organization.

Response (200 OK):

{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": 1,
      "name": "Production Email Alerts",
      "channel_type": "email",
      "organization_id": 1,
      "configuration": {
        "to": "alerts@company.com",
        "from": "slozy@company.com"
      },
      "enabled": true,
      "max_retries": 3,
      "retry_policy": "exponential_backoff",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:00:00Z"
    },
    {
      "id": 2,
      "name": "Operations Slack",
      "channel_type": "slack",
      "organization_id": 1,
      "configuration": {
        "webhook_url": "https://hooks.slack.com/services/T00/B00/xxx"
      },
      "enabled": true,
      "max_retries": 3,
      "retry_policy": "exponential_backoff",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:00:00Z"
    }
  ]
}

Supported channel_type values: email, slack, webhook, pagerduty, opsgenie.

Delivery channel implementations are in internal/notifications/channels.go (EmailChannel, SlackChannel, WebhookChannel).

---

POST /notifications/rules

Creates a notification rule that triggers alerts when specific conditions are met.

Request:

{
  "slo_id": 1,
  "rule_id": null,
  "channel_id": 1,
  "alert_type": "violation",
  "priority": "high",
  "subject": "SLO Violation Alert",
  "message": "API response time exceeded threshold of 99.95%",
  "max_retries": 3
}

Response (201 Created):

{
  "success": true,
  "message": "Notification created successfully",
  "data": {
    "id": 123,
    "slo_id": 1,
    "channel_id": 1,
    "status": "pending",
    "priority": "high",
    "created_at": "2026-06-09T14:30:00Z"
  }
}

---

POST /notifications/test

Sends a test notification through a specified channel to verify its configuration.

Request:

{
  "channel_id": 1,
  "subject": "Test Notification",
  "message": "This is a test alert from SLOzy"
}

Response (200 OK):

{
  "success": true,
  "message": "Test notification sent successfully"
}

Delivery Mechanism

The notification service (internal/notifications/service.go:22) supports:

• Async delivery: Notifications are queued and processed by background workers
• Retry with exponential backoff: Configurable via RetryDelay and RetryBackoffMultiplier
• Deduplication: Prevents duplicate notifications within a configurable time window
• Concurrent delivery: Multiple notifications can be sent simultaneously with a configurable concurrency limit

Error Codes

HTTP Status	Scenario
400	Invalid request body, missing required fields
404	Channel not found or disabled
409	Duplicate notification (within deduplication window)
500	Delivery failure, database error