Alerting API

Alerting endpoints configure where alert notifications go (integrations) and when they are sent (profiles). They control delivery of operational alert open/close transitions; they do not change detection. The signal model is in Violations, Alerts & Incidents.

Concepts

Integration — a delivery target. Supported types: Webhook (JSON POST with optional headers), Slack (incoming webhook), MicrosoftTeams (workflow webhook, Adaptive Card), PagerDuty (Events API v2), and ServiceNow (incident create/resolve).
Profile — a routing policy that sends open/close transitions to one or more integrations, with a cooldown. A rule references a profile via alertingProfileId.

Routing precedence: when an alert transitions, Lumetry routes it to the rule's alertingProfileId if set; otherwise to the default profile if one exists; otherwise to the deployment's fallback notification target when one is configured.

Permissions: reads require CanViewAlerts; integration create/update/test requires CanManageIntegrations; profile create/update requires CanManageAlertProfiles.

Integrations

`GET /api/alerting/integrations`

[
  {
    "id": 4,
    "name": "ops-webhook",
    "type": "Webhook",
    "endpointUrl": "https://hooks.example.com/lumetry",
    "headers": { "X-Auth": "•••" },
    "config": {},
    "hasSecret": false,
    "isEnabled": true,
    "createdAt": "2026-06-01T00:00:00Z",
    "updatedAt": "2026-06-01T00:00:00Z",
    "lastTestedAt": "2026-06-02T08:00:00Z",
    "lastDeliveryStatus": "Success",
    "lastDeliveryError": null
  }
]

Field	Meaning
`type`	`Webhook`, `Slack`, `MicrosoftTeams`, `PagerDuty`, or `ServiceNow`.
`endpointUrl`	Delivery URL: webhook target, Slack/Teams webhook URL, ServiceNow instance base URL, or optional PagerDuty regional endpoint override.
`headers`	Per-integration request headers (`Webhook` type only).
`config`	Non-secret, type-specific settings (e.g. ServiceNow `username`).
`hasSecret`	Whether a channel secret is stored. Secrets are never returned.
`isEnabled`	Whether it receives traffic.
`lastTestedAt` / `lastDeliveryStatus` / `lastDeliveryError`	Most recent test/delivery outcome.

`POST /api/alerting/integrations` · `PUT /api/alerting/integrations/{id}`

Body

{
  "name": "on-call",
  "type": "PagerDuty",
  "endpointUrl": "",
  "headers": {},
  "config": {},
  "secret": "<events-api-v2-routing-key>",
  "isEnabled": true
}

secret is write-only: omit it (or send null) on update to keep the stored value, send an empty string to clear it. Per-type requirements:

Type	`endpointUrl`	`config`	`secret`
`Webhook`	required	—	—
`Slack`	incoming webhook URL (required)	—	—
`MicrosoftTeams`	workflow webhook URL (required)	—	—
`PagerDuty`	optional regional override	—	Events API v2 routing key (required)
`ServiceNow`	instance base URL (required)	`username` (required)	password or API token (required)

`POST /api/alerting/integrations/{id}/test`

Runs a channel-aware connectivity test and returns the outcome: webhook/Slack/Teams post a visible test message, PagerDuty triggers and immediately resolves a test-scoped event, and ServiceNow performs an authenticated read without creating a ticket.

{ "integrationId": 4, "deliveryStatus": "Success", "deliveryError": null, "testedAt": "2026-06-02T09:00:00Z" }

Profiles

`GET /api/alerting/profiles`

[
  {
    "id": 2,
    "name": "Critical → on-call",
    "isEnabled": true,
    "isDefault": false,
    "notifyOnOpen": true,
    "notifyOnClose": true,
    "cooldownMinutes": 15,
    "integrationIds": [4, 7],
    "createdAt": "2026-06-01T00:00:00Z",
    "updatedAt": "2026-06-01T00:00:00Z"
  }
]

Field	Meaning
`isDefault`	If true, this profile handles rules with no explicit `alertingProfileId`. At most one default.
`notifyOnOpen` / `notifyOnClose`	Which lifecycle transitions are delivered.
`cooldownMinutes`	Minimum gap between notifications to suppress storms.
`integrationIds`	The integrations this profile fans out to.

`POST /api/alerting/profiles` · `PUT /api/alerting/profiles/{id}`

Body

{
  "name": "Critical → on-call",
  "isEnabled": true,
  "isDefault": false,
  "notifyOnOpen": true,
  "notifyOnClose": true,
  "cooldownMinutes": 15,
  "integrationIds": [4, 7]
}

Delivery semantics

Notification delivery is durable. Open/close transitions are queued for delivery with retry and exponential backoff on failure. This means a transient channel outage delays notifications but does not lose them.

Internal webhook targets are claimed by a delivery-capable collector. Each claim has a lease and single-use token, so a recovered or duplicated collector cannot overwrite the current owner's result. If no collector completes the delivery after the lease and configured grace, Lumetry creates at most one durable out-of-band fallback notification when a fallback target is configured.

Channels map transitions to their native lifecycle: Slack and Teams post a card on open and close; PagerDuty triggers an incident on open and resolves the same incident on close (retries never duplicate); ServiceNow creates an incident on open and resolves that same incident on close. Channel secrets are stored encrypted and are never exposed back through the API or logs.

A rule's link to a profile is the nullable alertingProfileId field on the rule (Rules API). Leave it null to use the default profile or the deployment's configured fallback target.

Integrations​

GET /api/alerting/integrations​

POST /api/alerting/integrations · PUT /api/alerting/integrations/{id}​

POST /api/alerting/integrations/{id}/test​

Profiles​

GET /api/alerting/profiles​

POST /api/alerting/profiles · PUT /api/alerting/profiles/{id}​

Delivery semantics​