Skip to main content
Use the webhook integration of a MongoDB Atlas project to send Atlas alerts to Flashduty On-call. Each Atlas alert maps to one Flashduty alert: it triggers when Atlas opens the alert and recovers automatically when Atlas closes or cancels it.

​
In Flashduty On-call

You can get the integration push URL in either of the following ways.

​
Use a dedicated integration

  1. In the Flashduty console, select Channel and open a channel
  2. Select Configuration → Integrations → Private integration, then click Add an integration
  3. Select MongoDB Atlas and click Save
  4. Open the new integration card and copy the Push URL

​
Use a shared integration

  1. In the Flashduty console, select Integration Center → Alert Events
  2. Select MongoDB Atlas and enter an integration name
  3. Configure the default route and select a channel. You can add more rules under Routes after creation
  4. Click Save and copy the generated Push URL

​
Configure MongoDB Atlas

Configuring the webhook integration requires the Project Owner role on the project or the Organization Owner role. Editing alert settings requires Project Owner or Project Alerts Manager.
1

Configure the project webhook integration

  1. Sign in to Atlas and select the organization and project in the top navigation bar
  2. In the sidebar, click the icon next to Project Overview to open Project Settings
  3. Open the Integrations tab and click Configure under Webhook Settings
  4. Paste the full Flashduty push URL into Webhook URL
  5. Leave Webhook Secret empty if you like. Flashduty authenticates the request by the integration_key in the push URL and does not verify X-MMS-Signature
  6. Click Save. Atlas does not send a request to the URL when you save
2

Add the webhook to your alert settings

  1. Click the alerts icon in the top right corner of Atlas, then select Alerts under Project
  2. To create an alert, click Add → New Alert. To change an existing one, edit it on the Alert Settings tab
  3. Select the alert category and condition
  4. In the Add Notifier drop-down menu, select Webhook. The URL defaults to the project webhook configured in the previous step
  5. Leave Headers Template and Body Template empty. Flashduty parses the default Atlas request body, and a custom template drops the fields it needs
  6. Set Severity as needed. Flashduty uses it for the alert severity, as described below
  7. Save the alert setting
Add the webhook notifier to every alert setting that should reach Flashduty.
3

Verify the lifecycle

Post test message to webhook under the Webhook notifier sends a test message (X-MMS-Event is alert.close and status is INFORMATIONAL). Flashduty returns success without creating an alert, so you can use it to check that the push URL is reachable.To verify the full flow, create a temporary alert setting that is easy to trigger, such as Connections above 1, then connect to the cluster so the alert opens and confirm that Flashduty receives it. Disconnect, wait for Atlas to close the alert, and confirm that the Flashduty alert recovers. Delete the temporary alert setting afterwards.
Atlas requires the webhook URL to be reachable from the internet and to return 2xx. After 24 hours of failed deliveries, Atlas disables the notification method and notifies the project owners. Delivery errors are listed in the Atlas Activity Feed.

​
Alert Key

Flashduty uses the alert id in the request body as the Alert Key. The Atlas documentation defines id as the unique identifier of the alert. The open, update, acknowledge, close, and cancel notifications of one alert carry the same id, so they land on the same Flashduty alert. Changes to status, currentValue, humanReadable, or the timestamps do not change the Alert Key. Flashduty rejects a request without id, because it could not be matched to its recovery.

​
Status and severity

Atlas sets the alert state in the X-MMS-Event request header: When a request has no X-MMS-Event header, Flashduty uses the body status instead: OPEN and TRACKING trigger, CLOSED and CANCELLED recover, and INFORMATIONAL is an informational alert. Other values are rejected. The severity comes from the body severity, which is the Severity set on the alert setting (host alerts default to Error): When the body has no severity or an unknown value, alerts that recover are Warning and informational alerts (alert.inform, such as Primary Elected) are Info. A recovery event keeps the original severity. Atlas evaluates host conditions on each node of a replica set, and each node’s alert has its own id, so they are separate Flashduty alerts. Use the host label to tell them apart. An informational alert is a point-in-time event. Each notification carries a new id, and Atlas never sends a close notification for it. These alerts do not recover automatically in Flashduty: close them by hand, or turn on the channel’s auto-resolve timeout.

​
Alert content

  • Title: metricName, or eventTypeName when it is empty, followed by on <resource> when a resource is known, for example CONNECTIONS on Cluster0
  • Description: humanReadable, which contains the project name, organization name, and alert details
  • Labels: alert_id, alert_config_id, group_id (project ID), event_type, type_name, mms_event, status, metric_name, current_value (value and units), cluster, replica_set, host, instance_name, processor_name, created, source (always mongodb-atlas), and resource (the first non-empty value of clusterName, replicaSetName, hostnameAndPort, instanceName, processorName)
The acknowledging user acknowledgingUsername and the acknowledgement comment are not written to labels.

​
Troubleshooting

  • The Atlas Activity Feed shows failed deliveries: check that Webhook URL is the full push URL including integration_key
  • Flashduty returns a parameter error: check that no Webhook Body Template is set and that the body contains id
  • No alerts arrive: check that the alert setting has a Webhook notifier and that the alert appears on the Atlas Open alerts tab
  • An alert does not recover: check that Atlas has closed the alert. Informational alerts (alert.inform) never recover
  • The severity is not what you expect: check Severity on the alert setting. See the severity section above for the mapping
For field definitions, see MongoDB Atlas webhook integration and Atlas alert settings.