Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Notifications API

11 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/notifications/alert-settings

Get the service alert thresholds

How long a service must be down, unhealthy or restarting before service.crashed, service.unhealthy and service.restart_loop are sent, when an incident closes, and when a backup counts as missed. Which channel receives which event is the channel's own event selection.

Response 200 · OK · application/json
SettingsView
  • backupGraceMinutesinteger (int64)required
    Extra time a scheduled backup gets after its due time before backup.missed is sent. 0 = automatic: a quarter of the schedule's interval, between 15 minutes and 6 hours.
  • crashGraceSecondsinteger (int64)required
    A container that stays down (or restarting) this long is announced as crashed. A restart Docker performed after a crash is announced at once.
  • flapIncidentsinteger (int64)required
    Incidents within the flap window that make a flapping service: announced once, then silent until it has been stable for a whole window.
  • flapWindowMinutesinteger (int64)required
    The window incidents are counted in, and how long a flapping service must be stable before its recovery is sent.
  • logLinesinteger (int64)required
    Runtime log lines attached to a crash or restart-loop message (redacted for the service's secrets). 0 attaches none.
  • loopRestartsinteger (int64)required
    Docker restarts within the loop window that make a restart loop.
  • loopWindowMinutesinteger (int64)required
    The window the restarts are counted in.
  • recoverAfterSecondsinteger (int64)required
    How long a service must look healthy before the incident is closed and service.recovered is sent.
  • unhealthyGraceSecondsinteger (int64)required
    The health check must keep failing this long before service.unhealthy is sent.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/notifications/alert-settings

Set the service alert thresholds

Replaces every threshold. Takes effect within a minute.

Request body · application/json · required
SettingsView
  • backupGraceMinutesinteger (int64)required
    Extra time a scheduled backup gets after its due time before backup.missed is sent. 0 = automatic: a quarter of the schedule's interval, between 15 minutes and 6 hours.
  • crashGraceSecondsinteger (int64)required
    A container that stays down (or restarting) this long is announced as crashed. A restart Docker performed after a crash is announced at once.
  • flapIncidentsinteger (int64)required
    Incidents within the flap window that make a flapping service: announced once, then silent until it has been stable for a whole window.
  • flapWindowMinutesinteger (int64)required
    The window incidents are counted in, and how long a flapping service must be stable before its recovery is sent.
  • logLinesinteger (int64)required
    Runtime log lines attached to a crash or restart-loop message (redacted for the service's secrets). 0 attaches none.
  • loopRestartsinteger (int64)required
    Docker restarts within the loop window that make a restart loop.
  • loopWindowMinutesinteger (int64)required
    The window the restarts are counted in.
  • recoverAfterSecondsinteger (int64)required
    How long a service must look healthy before the incident is closed and service.recovered is sent.
  • unhealthyGraceSecondsinteger (int64)required
    The health check must keep failing this long before service.unhealthy is sent.
Response 200 · OK · application/json
SettingsView
  • backupGraceMinutesinteger (int64)required
    Extra time a scheduled backup gets after its due time before backup.missed is sent. 0 = automatic: a quarter of the schedule's interval, between 15 minutes and 6 hours.
  • crashGraceSecondsinteger (int64)required
    A container that stays down (or restarting) this long is announced as crashed. A restart Docker performed after a crash is announced at once.
  • flapIncidentsinteger (int64)required
    Incidents within the flap window that make a flapping service: announced once, then silent until it has been stable for a whole window.
  • flapWindowMinutesinteger (int64)required
    The window incidents are counted in, and how long a flapping service must be stable before its recovery is sent.
  • logLinesinteger (int64)required
    Runtime log lines attached to a crash or restart-loop message (redacted for the service's secrets). 0 attaches none.
  • loopRestartsinteger (int64)required
    Docker restarts within the loop window that make a restart loop.
  • loopWindowMinutesinteger (int64)required
    The window the restarts are counted in.
  • recoverAfterSecondsinteger (int64)required
    How long a service must look healthy before the incident is closed and service.recovered is sent.
  • unhealthyGraceSecondsinteger (int64)required
    The health check must keep failing this long before service.unhealthy is sent.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/notifications/channels

List notification channels

Credentials are never returned; secrets holds masked hints of the ones that are set.

Response 200 · OK · application/json
ChannelListOutputBody
  • ChannelView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/notifications/channels

Add a notification channel

Kinds: email (SMTP: host, port, tls implicit|starttls|none, username, from, to; password in secrets), slack and discord (webhook URL in secrets.url), telegram (config.chatId, bot token in secrets.botToken) and webhook (URL in secrets.url; every request is signed with HMAC-SHA256 in the X-NebulaCtrl-Signature header). A webhook's signing secret is generated when omitted and returned once. Not idempotent: the response can carry that secret, so a repeated name answers 409 channel_conflict instead of replaying it. Requires the admin scope.

Request body · application/json · required
CreateChannelInputBody
  • ChannelConfig
  • enabledboolean
    Default true.
  • kindenum: email | slack | discord | telegram | webhookrequired
  • namestringrequired
  • ChannelRuleInput
  • ChannelSecretsInput
Response 201 · Created · application/json
CreateChannelOutputBody
  • ChannelViewrequired
  • signingSecretstring
    Webhook channels: the generated signing secret. Shown only in this response; store it now. Rotate it to get a new one.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictchannel_conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/notifications/channels/{channelId}

Get a notification channel

ParameterInTypeDescription
channelIdrequiredpathstring
Response 200 · OK · application/json
ChannelView
  • ChannelConfigrequired
  • createdAtstring (date-time)required
  • enabledbooleanrequired
  • idstringrequired
  • kindenum: email | slack | discord | telegram | webhookrequired
  • namestringrequired
  • ChannelRulerequired
  • map of stringrequired
    Masked hints of the stored secrets, keyed by name (url, botToken, password, signingSecret). A key is present when the secret is set; its value never reveals it.
  • ChannelStatsrequired
  • ChannelTestStaterequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/notifications/channels/{channelId}

Update a notification channel

Omitted fields stay as they are; empty credentials keep the stored ones. The kind can not change.

ParameterInTypeDescription
channelIdrequiredpathstring
Request body · application/json · required
PatchChannelInputBody
  • ChannelConfig
  • enabledboolean
  • namestring
  • ChannelRuleInput
  • ChannelSecretsInput
Response 200 · OK · application/json
ChannelView
  • ChannelConfigrequired
  • createdAtstring (date-time)required
  • enabledbooleanrequired
  • idstringrequired
  • kindenum: email | slack | discord | telegram | webhookrequired
  • namestringrequired
  • ChannelRulerequired
  • map of stringrequired
    Masked hints of the stored secrets, keyed by name (url, botToken, password, signingSecret). A key is present when the secret is set; its value never reveals it.
  • ChannelStatsrequired
  • ChannelTestStaterequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/notifications/channels/{channelId}

Delete a notification channel

Deletes the channel and its delivery log.

ParameterInTypeDescription
channelIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/notifications/channels/{channelId}/deliveries

List a channel's deliveries

The delivery log, newest first, kept for 30 days: status (pending, retrying, delivered, failed), attempts, the last error and the response code. Errors never contain credentials.

ParameterInTypeDescription
channelIdrequiredpathstring
statusqueryenum: pending | retrying | delivered | failedOnly deliveries in this status.
cursorquerystringOpaque cursor from a previous page's nextCursor
limitqueryinteger (int64)Page size (default 50, max 200)
Response 200 · OK · application/json
ChannelDeliveryPage
  • ChannelDelivery[] | nullrequired
  • nextCursorstring
    Present when older deliveries exist
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/notifications/channels/{channelId}/rotate-secret

Rotate a webhook signing secret

Webhook channels only. The new secret is returned once; deliveries are signed with it from now on.

ParameterInTypeDescription
channelIdrequiredpathstring
Response 200 · OK · application/json
RotateOutputBody
  • signingSecretstringrequired
    The new signing secret. Shown only in this response.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/notifications/channels/{channelId}/test

Send a test notification

Sends a test message through the channel right now and returns the delivery that records the result (status delivered or failed, with the error and response code). The test is not queued, retried, rate limited or deduplicated, and works on a disabled channel. It also updates the channel's test state.

ParameterInTypeDescription
channelIdrequiredpathstring
Response 200 · OK · application/json
ChannelDelivery
  • attemptsinteger (int64)required
  • bodystring
  • channelIdstringrequired
  • createdAtstring (date-time)required
  • deliveredAtstring (date-time)
  • eventTypestringrequired
  • MessageField[] | null
  • idstringrequired
  • isTestbooleanrequired
  • lastErrorstringrequired
    Why the last attempt failed; credentials are masked.
  • maxAttemptsinteger (int64)required
  • nextAttemptAtstring (date-time)
  • projectIdstring
  • responseCodeinteger (int64)
    HTTP status or SMTP reply code of the last attempt.
  • severityenum: info | warning | errorrequired
  • statusenum: pending | retrying | delivered | failedrequired
  • titlestringrequired
  • urlstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/notifications/event-types

List notification event types

The events a channel can subscribe to, grouped, with their default severity and whether new channels subscribe by default.

Response 200 · OK · application/json
EventTypesOutputBody
  • ChannelEventType[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.