Skip to main content
Version: 1.4 (Current)

Notification rules API

A notification rule decides when ToBeAlert sends a notification, for which alerts, through which method and to whom. Concepts, triggers, conditions and the rule editor are described in Notification rules (Web UI).

All requests need an API key in the Authorization: Key <api-key> header.

Endpoints​

MethodPathPermissionDescription
GET/api/notification/rulesread:notificationsList rules (paging)
GET/api/notification/rule/<id>read:notificationsGet one rule
POST/api/notification/rulewrite:notificationsCreate a rule. At present the key also needs admin (or admin:policies)
PUT/api/notification/rule/<id>write:notificationsUpdate a rule (only the fields you send)
DELETE/api/notification/rule/<id>write:notificationsDelete a rule
POST/api/notification/rule/previewread:notificationsBuild the message a rule would send, without sending it — see Preview
GET/api/notification/rules/historyread:notificationsExecution history of all rules
GET/api/notification/rule/<id>/historyread:notificationsExecution history of one rule
DELETE/api/notification/rules/historyadmin:notificationsDelete execution history rows

Rule fields​

FieldTypeDefaultDescription
nameString—Rule name
descriptionString—Description
priorityInteger0Evaluation order, lower first
statusStringactiveactive or inactive
conditionsObjectnoneAlert filters, in the same format the rule editor saves ({"operator": "AND", "clauses": [...]}). Empty = every alert
triggerString—post_receive, status_change, take_action, or recurring for scheduled rules
recurrent / recurrentConfigBoolean / Objectfalse / nullSchedule of a recurring rule
allDayBooleantruetrue: the rule may notify at any time. false: only inside the daily window startTime–endTime
startTime / endTimeISO 8601nullDaily window. Only the hour and minute are used. Required when allDay is false
methodString—Notification method ID
methodActionsObject or JSON string—Recipients and message settings for the method (what the Actions card of the editor saves)
notificationGroupsArray[]Notification group IDs used as recipients when the method actions name none

Active hours​

  • A rule created without allDay is active all day.
  • allDay: false without both startTime and endTime is rejected with 400 (startTime and endTime are required when allDay is false), on create and on update.
curl -X POST "https://your-tobealert.com:9000/api/notification/rule" \
-H "Authorization: Key <api-key>" \
-H "Content-Type: application/json" \
-d '{
"name": "j.doe-critical-db",
"description": "Critical alerts on db01 to John Doe",
"trigger": "post_receive",
"conditions": {"operator": "AND", "clauses": [
{"key": "resource", "op": "=", "value": "db01"},
{"key": "severity", "op": "IN", "value": ["critical"]}
]},
"method": "<email-method-id>",
"methodActions": {"to": {"method": "users", "users": ["john.doe@example.com"]}}
}'

Triggers​

TriggerFires when
post_receiveA new alert is received, or an open alert changes severity
status_changeAn alert's status changes. Conditions may also use prev_status
take_actionA user performs an action on an alert (ack, shelve, close, …). Conditions may also use action and user (login of who performed it)
recurringOn the schedule in recurrentConfig

The severity operators more_severe_than / less_severe_than work in rule conditions the same way as in TQL.

Preview​

POST /api/notification/rule/preview renders the message a rule would send for one alert, using the same builders as the real send. It does not send anything, does not run code method scripts and does not write history. The rule does not need to be saved: send the settings you want to try.

Body fieldRequiredDescription
methodYesNotification method ID
methodActionsNoRecipients and message settings (object or JSON string), as in the rule
alertIdNoAlert to render. Without it, a sample alert is used (web01 / HighCPU, severity major)
kindNoopen (default) or close. With close the alert is rendered as closed and the rule's close settings (closeConfig) are used
notificationGroupsNoGroup IDs, as in the rule

Permissions: read:notifications. With alertId, the key also needs read:alerts and must be allowed to see that alert.

curl -X POST "https://your-tobealert.com:9000/api/notification/rule/preview" \
-H "Authorization: Key <api-key>" \
-H "Content-Type: application/json" \
-d '{"method": "<email-method-id>", "kind": "open",
"methodActions": {"to": {"method": "users", "users": ["john.doe@example.com"]},
"subject": {"enabled": true, "hostValue": "[%severity%] %resource% - %event%"}}}'

Response​

The shape depends on the method type. Every response has status, kind, sample (true when the sample alert was used), alertId and warnings.

Method typeFields
Emailtype: "email", subject, body (HTML), format: "html", from, fromDisplayName, to, cc, bcc (lists of addresses)
Telegramtype: "telegram", body, format (html or markdown), chatId
Codetype: "code", body: null. The method script defines the content
{
"status": "ok",
"type": "email",
"kind": "open",
"sample": true,
"alertId": null,
"subject": "[major] web01 - HighCPU",
"body": "<html>…</html>",
"format": "html",
"from": "alerts@example.com",
"fromDisplayName": "ToBeAlert",
"to": ["john.doe@example.com"],
"cc": [],
"bcc": [],
"warnings": []
}

Configuration problems do not fail the request; they come back in warnings, for example Cannot send email notification: missing recipients, Template not found (<id>), Notification group not found (<id>), CC is enabled but has no address, The severity graph is not included in sent emails, The notification method is disabled: nothing is sent, alsoNotifyOnClose is off: nothing is sent when the alert closes, or Cannot send telegram notification: missing chat ID.

Errors​

StatusWhen
400Body is not a JSON object, method missing, methodActions not an object, kind not open/close, alertId not a string, notificationGroups not a list of IDs
403alertId sent without read:alerts, or the alert is not visible to the key
404Method or alert not found