Configure Outage alerts (single threshold), profiles, and daily digest settings for an organization. Members can read settings; owners and admins can change them with a write scope.
The dashboard uses one Outage after duration per monitor or profile. The API still returns edgeOffline mirrored from longOutage for compatibility; webhooks may still emit edge_offline when silence is due to the Edge device or network.
Authentication
Authorization: Bearer <user_or_service_token>
Use a user token or a service token for the same organization. Monitor tokens cannot access these routes.
Endpoint map
| Method | Path | Who can change |
|---|---|---|
GET | /v1/organizations/:org_id/alerts | Member (read) |
PUT | /v1/organizations/:org_id/alerts | Owner / admin (write) |
POST | /v1/organizations/:org_id/alerts/threshold-notice | Owner / admin: dismiss auto-raise notice |
GET | /v1/organizations/:org_id/alerts/monitors | Member |
PUT | /v1/organizations/:org_id/alerts/monitors | Owner / admin: batch monitor updates |
GET | /v1/organizations/:org_id/alerts/profiles | Member |
POST | /v1/organizations/:org_id/alerts/profiles | Owner / admin |
GET | /v1/organizations/:org_id/alerts/profiles/:profile_id | Member |
PUT | /v1/organizations/:org_id/alerts/profiles/:profile_id | Owner / admin |
DELETE | /v1/organizations/:org_id/alerts/profiles/:profile_id | Owner / admin |
POST | /v1/organizations/:org_id/alerts/profiles/:profile_id/webhook-secret | Owner / admin: rotate profile webhook secret |
POST | /v1/organizations/:org_id/alerts/webhook-secret | Owner / admin: rotate org webhook secret |
POST | /v1/organizations/:org_id/alerts/test | Owner / admin: send test notification |
GET | /v1/organizations/:org_id/alerts/deliveries | Member: recent delivery log |
GET | /v1/monitors/:monitor_id/alert-settings | Member |
PUT | /v1/monitors/:monitor_id/alert-settings | Owner / admin |
DELETE | /v1/monitors/:monitor_id/alert-settings | Owner / admin: clear overrides |
Get organization alert settings
GET /v1/organizations/:org_id/alerts
Authorization: Bearer <token>
Response 200 (excerpt)
{
"data": {
"longOutage": { "enabled": true, "thresholdSec": 300 },
"edgeOffline": { "enabled": true, "thresholdSec": 300 },
"digest": { "enabled": false, "maxDurationSec": 15 },
"email": { "enabled": true, "recipients": ["ops@example.com"] },
"webhook": { "enabled": false, "url": null, "secret": null }
},
"profiles": { "profiles": [] },
"limits": {
"ingestIntervalSec": 60,
"minOutageThresholdSec": 90,
"minEdgeOfflineSec": 90
},
"canManage": true,
"thresholdsRaisedNotice": null
}
| Field | Description |
|---|---|
limits.minOutageThresholdSec | Minimum Outage after (ceil(1.5× org data interval); per-monitor rows include their own floor) |
limits.minEdgeOfflineSec | Deprecated mirror of minOutageThresholdSec (#371) |
canManage | true for owners and admins |
webhook.secret | Masked signing secret if configured |
webhookHeaders | Custom headers configured for the org webhook ({ name, set: true } only; values are never returned) |
Update organization alert settings
PUT /v1/organizations/:org_id/alerts
Authorization: Bearer <token>
Content-Type: application/json
{
"longOutage": { "enabled": true, "thresholdSec": 300 },
"edgeOffline": { "enabled": true, "thresholdSec": 300 },
"digest": { "enabled": true, "maxDurationSec": 15 },
"email": { "enabled": true, "recipients": ["ops@example.com"] },
"webhook": { "enabled": true, "url": "https://hooks.example.com/orbimon" }
}
Thresholds below limits return 400 invalid_request.
Include webhookHeaders in the same request to replace the org destination’s custom headers (owners and admins only). Send the full list on each update. Each item is either { "name": "Header-Name", "value": "…" } to set a value, or { "name": "Header-Name", "keep": true } to keep an existing value without resending it. Names not in the list are removed. Responses include only name and set flags, for example { "name": "Authorization", "set": true }.
Custom headers
Alert webhooks support up to 5 optional custom HTTP headers per destination (organization default or a profile’s own webhook URL). Profiles that use organization channels inherit the organization’s headers.
- Header names must be 1 to 64 characters and use RFC 7230 token characters. Names are unique case-insensitively.
- Header values are 1 to 1024 printable ASCII characters (no CR, LF, or NUL).
- Values are write-only: after you save, the API only reports which names are set. You cannot read values back.
- These names are reserved and cannot be set:
Content-Type,Content-Length,Host,Connection,Transfer-Encoding,User-Agent, and any name starting withX-Orbimon-. - Orbimon always sends
X-Orbimon-Timestamp,X-Orbimon-Signature,X-Orbimon-Event, andX-Orbimon-Delivery. Your custom headers cannot override them.
Example (organization settings):
PUT /v1/organizations/:org_id/alerts
Authorization: Bearer <token>
Content-Type: application/json
{
"webhook": { "enabled": true, "url": "https://hooks.example.com/orbimon" },
"webhookHeaders": [
{ "name": "Authorization", "value": "Bearer <your-token>" }
]
}
Use the same webhookHeaders field on PUT /v1/organizations/:org_id/alerts/profiles/:profile_id for a profile that defines its own webhook URL.
Per-monitor settings
GET /v1/monitors/:monitor_id/alert-settings
Authorization: Bearer <token>
Returns effective settings for one monitor (organization defaults, profile, and overrides).
PUT /v1/monitors/:monitor_id/alert-settings
Authorization: Bearer <token>
Content-Type: application/json
{
"profileId": "prof_…",
"longOutage": { "enabled": true, "thresholdSec": 120 },
"timezone": "Europe/Madrid"
}
Test notification
POST /v1/organizations/:org_id/alerts/test
Authorization: Bearer <token>
Content-Type: application/json
{ "channel": "email" }
channel may be email or webhook.
Recent deliveries
GET /v1/organizations/:org_id/alerts/deliveries?limit=50
Authorization: Bearer <token>
Returns delivery attempts newest first. The daily digest also writes one skipped row per monitor when it does not send, for example digest off, digest on, no email recipients, quiet day, nothing to report, or query failed. These rows have attempt: 0, skipped: true, and a readable error reason, so a silent digest leaves an audit trail.