Skip to main content

Notifications

All notification endpoints require authentication and the settings.notifications permission.

Channels​

GET /notifications/channels​

List all configured notification channels.

Response

{
  "channels": [
    {
      "id": "smtp",
      "enabled": true,
      "config": {
        "host": "smtp.example.com",
        "port": 587,
        "from": "alerts@example.com"
      }
    },
    { "id": "telegram", "enabled": false, "config": {} },
    { "id": "slack", "enabled": false, "config": {} },
    { "id": "webhook", "enabled": false, "config": {} }
  ]
}

PUT /notifications/channels/:type​

Update a channel's configuration. Supported types: smtp, telegram, slack, webhook.

Request body — SMTP

{
  "enabled": true,
  "config": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "alerts@example.com",
    "password": "smtp-password",
    "from": "alerts@example.com",
    "tls": true
  }
}

Request body — Telegram

{
  "enabled": true,
  "config": {
    "botToken": "123456:ABC-DEF...",
    "chatId": "-1001234567890"
  }
}

Request body — Slack

{
  "enabled": true,
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/..."
  }
}

Request body — Webhook

{
  "enabled": true,
  "config": {
    "url": "https://example.com/hooks/gatwy",
    "method": "POST",
    "headers": { "X-Secret": "token" }
  }
}

Response

{ "ok": true }

POST /notifications/channels/:type/test​

Send a test notification through a channel.

Request body: Optional config overrides (same shape as above).

Response

{ "ok": true }

Rules​

GET /notifications/rules​

List all notification rules.

Response

{
  "rules": [
    {
      "id": "rule_abc",
      "name": "Alert on failed logins",
      "enabled": true,
      "events": ["auth.login_failed"],
      "conditionLogic": "and",
      "conditions": [],
      "cadence": "instant",
      "actions": [{ "channel": "smtp", "recipients": ["admin@example.com"] }],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "lastTriggeredAt": "2024-01-02T00:00:00.000Z"
    }
  ]
}

POST /notifications/rules​

Create a notification rule.

Request body

{
  "name": "Alert on failed logins",
  "enabled": true,
  "events": ["auth.login_failed"],
  "conditionLogic": "and",
  "conditions": [
    { "field": "ipAddress", "operator": "not_in", "value": ["192.168.1.0/24"] }
  ],
  "cadence": "instant",
  "actions": [
    { "channel": "smtp", "recipients": ["admin@example.com"] }
  ]
}

Response

{
  "rule": { "id": "rule_xyz", "name": "Alert on failed logins", "enabled": true, "..." : "..." }
}

PUT /notifications/rules/:id​

Update an existing rule. All fields are optional.

Request body (all fields optional)

{
  "name": "Updated rule name",
  "enabled": false,
  "events": ["auth.login_failed", "auth.account_locked"]
}

Response

{ "rule": { "..." : "..." } }

PATCH /notifications/rules/:id/toggle​

Toggle a rule on or off without sending the full body.

Response

{ "ok": true, "enabled": false }

DELETE /notifications/rules/:id​

Delete a rule.

Response

{ "ok": true }

Recipients​

GET /notifications/recipients​

List all users and roles available as notification recipients.

Response

{
  "users": [
    { "id": "user_abc", "username": "alice", "email": "alice@example.com" }
  ],
  "roles": [
    { "id": "role_abc", "name": "admin" }
  ]
}

Notification Log​

GET /notifications/log​

View the notification delivery history.

Query parameters

ParamTypeDescription
statusstringFilter by delivery status (sent, failed, pending)
rule_idstringFilter by rule ID
pagenumberPage number
limitnumberResults per page

Response

{
  "entries": [
    {
      "id": "log_abc",
      "ruleId": "rule_xyz",
      "ruleName": "Alert on failed logins",
      "channel": "smtp",
      "status": "sent",
      "sentAt": "2024-01-01T00:00:00.000Z",
      "error": null
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 25
}

POST /notifications/log/:id/retry​

Retry a failed notification delivery.

Response

{ "ok": true }

DELETE /notifications/log/:id​

Delete a single log entry.

Response

{ "ok": true }

DELETE /notifications/log​

Bulk-delete log entries.

Query parameters

ParamTypeDescription
statusstringDelete entries with this status
rule_idstringDelete entries for this rule
beforeISO8601Delete entries created before this timestamp

Response

{ "ok": true, "deleted": 17 }

Retention Settings​

GET /notifications/settings​

Get log retention settings.

Response

{ "retentionDays": 90 }

PUT /notifications/settings​

Update log retention.

Request body

{ "retentionDays": 30 }

Response

{ "ok": true, "retentionDays": 30 }