Docs Menu

Docs HomeMongoDB Cloud Manager

Create an Alert Configuration

On this page

  • Resource
  • Request Path Parameters
  • Request Query Parameters
  • Request Body Parameters
  • Response
  • Example Request
  • Example Response
  • Response Header
  • Response Body

Note

Groups and projects are synonymous terms. Your {PROJECT-ID} is the same as your project id. For existing groups, your group/project id remains the same. This page uses the more familiar term group when referring to descriptions. The endpoint remains as stated in the document.

Base URL: https://cloud.mongodb.com/api/public/v1.0

POST /groups/{PROJECT-ID}/alertConfigs

All request path parameters are required.

Parameter
Type
Description
PROJECT-ID
string
Unique identifier for this Project.

The following query parameters are optional:

Name
Type
Necessity
Description
Default
pretty
boolean
Optional
false
envelope
boolean
Optional

Flag that indicates whether or not to wrap the response in an envelope.

Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

For endpoints that return one result, the response body includes:

Name
Description
status
HTTP response code
envelope
Expected response body
false

Note

Alert configurations vary. An alert configuration may only include a subset of these elements.

Name
Type
Description
enabled
boolean
If omitted, the configuration is disabled.
eventTypeName
Required
string

The type of event that triggers an alert.

Values include:

Agent

Automation Configuration

Backup

BI Connector

Billing

Cluster

Data Explorer Accessed

Disk Backup

Host

Organization

Project

Replica Set

Support Case

Team

User

To review the full list of events that generate alerts and their descriptions, see Alert Types.

matchers.fieldName
string

Name of the field in the target object to match on.

  • Host alerts support these fields:

    • HOSTNAME

    • PORT

    • HOSTNAME_AND_PORT

    • REPLICA_SET_NAME

    • TYPE_NAME

  • Replica set alerts support these fields:

    • REPLICA_SET_NAME

    • SHARD_NAME

    • CLUSTER_NAME

  • Sharded cluster alerts support these fields:

    • CLUSTER_NAME

    • SHARD_NAME

All other types of alerts do not support matchers.

matchers.operator
string

Operator to test the field's value. Accepted values are:

  • EQUALS

  • NOT_EQUALS

  • CONTAINS

  • NOT_CONTAINS

  • STARTS_WITH

  • ENDS_WITH

  • REGEX

matchers.value
string

Value to test with the specified operator.

If matchers.fieldName is set to TYPE_NAME, you can match on the following values:

  • PRIMARY

  • SECONDARY

  • STANDALONE

  • CONFIG

  • MONGOS

matchers
object array

Rules to apply when matching an object against this alert configuration. Only entities that match all these rules are checked for an alert condition.

You can filter using the matchers array only when the eventTypeName specifies an event for a host, replica set, or sharded cluster.

metricThreshold.metricName
string
Name of the metric to check. Supports the same values as the metricName field of the alerts resource.
metricThreshold.mode
string
Set to AVERAGE to compute the average of this metric.
metricThreshold.operator
string

Operator to apply when checking the current metric value against the threshold value. Accepted values are:

  • GREATER_THAN

  • LESS_THAN

metricThreshold.threshold
number
Threshold value outside of which an alert is triggered.
metricThreshold.units
string

Units for the threshold value. Depends on the type of metric.

Example

A metric that measures memory consumption would have a byte measurement, while a metric that measures time would have a time unit.

Accepted values are:

  • RAW

  • BITS

  • BYTES

  • KILOBITS

  • KILOBYTES

  • MEGABITS

  • MEGABYTES

  • GIGABITS

  • GIGABYTES

  • TERABYTES

  • PETABYTES

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

metricThreshold
object
Threshold that will cause an alert to be triggered. Required if "eventTypeName" : "OUTSIDE_METRIC_THRESHOLD".
notifications.apiToken
string

Slack API token or Bot token. Required if "notifications.typeName" : "SLACK". If the token later becomes invalid, Cloud Manager sends an email to the Project owner and eventually removes the token.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.channelName
string
Slack channel name. Required if "notifications.typeName" : "SLACK".
notifications.datadogApiKey
string

DataDog API Key. Found in the DataDog dashboard. Required if "notifications.typeName" : "DATADOG".

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.delayMin
number
Number of minutes to wait after an alert condition is detected before sending out the first notification.
notifications.emailAddress
string
Email address to which to send notification. Required if "notifications.typeName" : "EMAIL".
notifications.emailEnabled
boolean

Determines if email notifications should be sent. Required if:

  • "notifications.typeName" : "GROUP"

  • "notifications.typeName" : "USER"

notifications.intervalMin
number
Number of minutes to wait between successive notifications for unacknowledged alerts that are not resolved.
notifications.webhookSecret
string

A value used to authenticate with the Webhook that accepts and forwards the notification. You can explicitly declare a secret only in a request that has both:

  • A notifications.typeName of WEBHOOK

  • An explicitly declared notifications.webhookURL

You can configure a webhookSecret for a default webhookURL only either on the Integrations page, or with the Integrations API.

To explicitly declare a webhookURL without a webhookSecret, omit this field.

Note

After creating a webhook notification, the URL will appear partially redacted when you view or edit the alert, and the secret will appear completely redacted.

notifications.webhookUrl
string

URL for the webhook that triggers this notification. If you do not explicitly declare a webhookUrl, your request will use the default webhookUrl set either on the Integrations page, or with the Integrations API.

Note

After creating a webhook notification, the URL will appear partially redacted when you view or edit the alert, and the secret will appear completely redacted.

notifications.microsoftTeamsWebhookUrl
string

Microsoft Teams channel incoming webhook URL. Required if "notifications.typeName" : "MICROSOFT_TEAMS".

Note

When you view or edit the alert for a webhook notification, the URL appears partially redacted, and the secret appears completely redacted.

notifications.mobileNumber
string
Mobile number to send SMS messages to. Required if "notifications.typeName" : "SMS".
notifications.notificationToken
string

A HipChat API token. Required if "notifications.typeName" : "HIP_CHAT". If the token later becomes invalid, Cloud Manager sends an email to the Project owner and eventually removes the token.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.role
string

One or more project roles that receive the configured alert. Accepted values include:

Role Value in API
Role
GROUP_AUTOMATION_ADMIN
GROUP_BACKUP_ADMIN
GROUP_BILLING_ADMIN
Project Billing Admin
GROUP_DATA_ACCESS_ADMIN
GROUP_DATA_ACCESS_READ_ONLY
GROUP_DATA_ACCESS_READ_WRITE
GROUP_MONITORING_ADMIN
GROUP_OWNER
GROUP_READ_ONLY
GROUP_USER_ADMIN

If you include this field, Cloud Manager sends alerts only to users assigned the roles you specify in the array. If you omit this field, Cloud Manager sends alerts to users assigned any role.

Configurable for GROUP notifications types.

notifications.roomName
string
HipChat room name. Required if "notifications.typeName" : "HIP_CHAT".
notifications.serviceKey
string
PagerDuty integration key. Required if "notifications.typeName" : "PAGER_DUTY".
notifications.smsEnabled
boolean

Flag indicating SMS notifications must be sent. Required if:

  • "notifications.typeName" : "GROUP"

  • "notifications.typeName" : "USER"

notifications.teamId
string
Unique identifier of a team.
notifications.typeName
string

Type of alert notification. Accepted values are:

  • EMAIL

  • GROUP (Project)

  • HIPCHAT

  • ORG

  • PAGER_DUTY

  • SLACK

  • SMS

  • TEAM

  • USER

  • WEBHOOK

  • MICROSOFT_TEAMS

notifications.username
string
Name of a Cloud Manager user to which to send notifications. Specify a user in the Project that owns the alert configuration. Required if "notifications.typeName" : "USER".
notifications
Required
object array
Notifications to send when an alert condition is detected.
threshold.operator
string

Operator to apply when checking the current metric value against the threshold value.

  • GREATER_THAN

  • LESS_THAN

threshold.threshold
number
Threshold value outside of which an alert is triggered.
threshold
object

Threshold that will cause an alert to be triggered. Required if:

  • "eventTypeName" : "TOO_FEW_HEALTHY_MEMBERS"

  • "eventTypeName" : TOO_MANY_UNHEALTHY_MEMBERS

The response includes the alert configuration details:

Note

Alert configurations vary. An alert configuration may only include a subset of these elements.

Name
Type
Description
created
string
Timestamp in ISO 8601 date and time format in UTC when this alert configuration was created.
enabled
boolean
Flag indicating this alert configuration enabled.
eventTypeName
string
Type of event that triggers an alert.
groupId
string
Unique identifier of the Project that owns this alert configuration.
id
string
Unique identifier of the alert configuration.
links
array of objects

One or more links to sub-resources and/or related resources. The relation-types between URLs are explained in the Web Linking Specification.

matchers
array of objects
Rules to apply when matching an object against this alert configuration.
matchers
.[n].fieldName
string
Name of the field in the target object that you wanted this configuration to match.
matchers
.[n].operator
string
Comparison operator to apply when checking the current metric value against matcher.[n].value.
matchers
.[n].value
string
Value to match or exceed using matchers.[n].operator.
metricThreshold
object
Value and means of comparison that triggers an alert.
metricThreshold
.metricName
string
Name of the metric to check. Supports the same values as the metricName field of the alerts resource.
metricThreshold
.mode
string
Average value of this metric.
metricThreshold
.operator
string
Comparison operator that Cloud Manager applied when checking the current metric value against the threshold value.
metricThreshold
.threshold
number
Value of metricThreshold.metricName that, when exceeded, triggers an alert.
metricThreshold
.units
string
Units of capacity or time that define the scope of the metricThreshold.threshold.
notifications
array of objects
One or more targets for Cloud Manager to send notifications when an alert condition is detected.
notifications.[n]
.apiToken
string

Slack API token token. Cloud Manager returns this value if you set notifications.[n].typeName to SLACK.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.channelName
string
Slack channel name. Cloud Manager returns this value if you set notifications.[n].typeName to SLACK.
notifications.[n]
.datadogApiKey
string

DataDog API Key. Cloud Manager returns this value if you set notifications.[n].typeName to DATADOG.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.delayMin
number
Number of minutes to wait after an alert condition is detected before sending out the first notification.
notifications.[n]
.emailAddress
string
Email address to which to send notification. Cloud Manager returns this value if you set notifications.[n].typeName to EMAIL.
notifications.[n]
.emailEnabled
boolean
Flag indicating email notifications must be sent. Cloud Manager returns this value if you set notifications.[n].typeName to ORG, GROUP, or USER.
notifications.[n]
.intervalMin
number
Number of minutes to wait between successive notifications for unacknowledged alerts that are not resolved.
notifications.[n]
.microsoftTeamsWebhookUrl
string

Microsoft Teams channel incoming webhook URL. Cloud Manager returns this value if you set notifications.[n].typeName to MICROSOFT_TEAMS.

Note

When you view or edit the alert for a webhook notification, the URL appears partially redacted, and the secret appears completely redacted.

notifications.[n]
.mobileNumber
string
Mobile number to which alert notifications are sent. Cloud Manager returns this value if you set notifications.[n].typeName to SMS.
notifications.[n]
.notificationToken
string

HipChat API token. Cloud Manager returns this value if you set notifications.[n].typeName to HIP_CHAT.

If the token later becomes invalid, MongoDB Atlas sends an email to the Project Owner and eventually removes the token.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.opsGenieApiKey
string

OpsGenie Alert API key. Cloud Manager returns this value if you set notifications.[n].typeName to OPS_GENIE.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.opsGenieRegion
string
Region that indicates which API URL to use. Cloud Manager returns this value if you set notifications.[n].typeName to OPS_GENIE.
notifications.[n]
.roles
array of strings
Cloud Manager role in current Project or Organization. Cloud Manager returns this value if you set notifications.[n].typeName to ORG or GROUP.
notifications.[n]
.roomName
string
HipChat room name. Cloud Manager returns this value if "notifications.typeName" : "HIP_CHAT.
notifications.[n]
.serviceKey
string

PagerDuty service key. Cloud Manager returns this value if you set notifications.[n].typeName to PAGER_DUTY.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.smsEnabled
boolean
Flag indicating text notifications must be sent. Cloud Manager returns this value if you set notifications.[n].typeName to ORG, GROUP, or USER.
notifications.[n]
.teamId
string
Unique identifier of the team that receives this notification.
notifications.[n]
.teamName
string
Label for the team that receives this notification.
notifications.[n]
.typeName
string
Means by which you want Cloud Manager to send you notification of an alert.
notifications.[n]
.username
string
Name of a Cloud Manager user to which to send notifications. Cloud Manager returns this value if you set notifications.[n].typeName to USER.
notifications.[n]
.victorOpsApiKey
string

VictorOps API key.

If the key later becomes invalid, MongoDB Atlas sends an email to the Project Owner and eventually removes the key.

Cloud Manager returns this value if you set notifications.[n].typeName to VICTOR_OPS.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.victorOpsRoutingKey
string

VictorOps routing key.

If the key later becomes invalid, MongoDB Atlas sends an email to the Project Owner and eventually removes the key.

Cloud Manager returns this value if you set notifications.[n].typeName to VICTOR_OPS.

Note

After you create a third-party integration that requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the UI.

  • Query the third-party integration settings through the API.

notifications.[n]
.webhookSecret
string

A value used to authenticate with the Webhook that accepts and forwards the notification.

Cloud Manager returns this value if you set notifications.[n].typeName to WEBHOOK and either:

  • You set notification.[n].webhookSecret to a non-empty string

  • You set a default webhookSecret either on the Integrations page, or with the Integrations API

Note

After creating a webhook notification, the URL will appear partially redacted when you view or edit the alert, and the secret will appear completely redacted.

notifications.[n]
.webhookUrl
string

URL for the webhook that triggers this notification.

Cloud Manager returns this value if you set notifications.[n].typeName to WEBHOOK and either:

  • You set notification.[n].webhookURL to a non-empty string

  • You set a default webhookUrl either on the Integrations page, or with the Integrations API

Note

After creating a webhook notification, the URL will appear partially redacted when you view or edit the alert, and the secret will appear completely redacted.

threshold
object
Threshold that triggers an alert. Cloud Manager returns this value if eventTypeName is any value other than OUTSIDE_METRIC_THRESHOLD.
threshold
.operator
string
Comparison operator that Cloud Manager applied when checking the current metric value against the threshold value.
threshold
.threshold
number
Value that, when exceeded, Cloud Manager triggers an alert.
threshold
.units
string
Units of capacity or time that define the scope of the threshold.threshold.
typeName
string
This field is deprecated and is ignored.
updated
string
Timestamp in ISO 8601 date and time format in UTC when this alert configuration was last updated.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--include \
--request POST "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/alertConfigs" \
--data '
{
"groupId" : "{PROJECT-ID}",
"eventTypeName" : "RESYNC_REQUIRED",
"enabled" : true,
"notifications" : [ {
"typeName" : "GROUP",
"intervalMin" : 5,
"delayMin" : 0,
"smsEnabled" : false,
"emailEnabled" : true
} ]
}'
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Date: {dateInUnixFormat}
WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=false
Content-Length: {requestLengthInBytes}
Connection: keep-alive
HTTP/1.1 200 OK
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}
X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}
{
"created" : "2014-04-23T14:29:18Z",
"enabled" : true,
"groupId" : "{PROJECT-ID}",
"id" : "{ALERT-CONFIG-ID}",
"links" : [],
"matchers" : [ ],
"notifications" : [ {
"delayMin" : 0,
"emailEnabled" : true,
"intervalMin" : 5,
"smsEnabled" : false,
"typeName" : "GROUP"
} ],
"updated" : "2014-04-23T14:29:18Z"
}
←  Get All Alert Configurations for a ProjectGet an Alert Configuration →