You can configure Atlas to send alert notifications to a webhook endpoint as HTTP POST requests for programmatic processing. Webhooks allow you to integrate Atlas alerts with custom monitoring systems, incident management platforms, or automation workflows.
Required Access
To integrate Atlas with webhooks, you must have Organization Owner or Project Owner access to the project.
Configure a Webhook Integration
In Atlas, go to the Project Settings page.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click the icon next to Project Overview.
The Project Settings page displays.
In Atlas, go to the Project Integrations page.
Click the Integrations tab.
The Project Integrations page displays.
To send alerts to your webhook, configure alert notifications. To learn more, see Configure Alert Settings.
Request Headers
Atlas includes the following HTTP headers with each webhook request:
Header | Description |
|---|---|
| Indicates the alert state. Possible values:
|
| (Optional) If you specify a secret in the Webhook Secret field, Atlas includes this header. Contains the Base64-encoded HMAC-SHA-1 signature of the request body. Atlas creates the signature using the provided secret. Use this header to verify that the webhook request originated from Atlas. |
Request Body
The request body contains a JSON document that uses the same format as the Atlas Administration API Alerts resource. The payload includes key fields such as:
id: Unique identifier for the alert.eventTypeName: Type of event that triggered the alert.created: Timestamp when the alert was created.status: Current status of the alert (e.g.,OPEN,CLOSED).humanReadable: Human-readable description of the alert. This field contains the project name and organization name in the format "Project: [project name] Organization: [org name]" along with other alert details.
For a complete list of fields, refer to the Atlas Administration API Get All Project Alerts documentation.
Example Webhook Payload
The following example shows a sample webhook payload for a disk space alert:
{ "id": "5d1b6f8e8c2e4e2d3c4a5b6c", "groupId": "5d1b6f8e8c2e4e2d3c4a5b6d", "eventTypeName": "OUTSIDE_METRIC_THRESHOLD", "status": "OPEN", "created": "2024-01-15T10:30:00Z", "updated": "2024-01-15T10:30:00Z", "lastNotified": "2024-01-15T10:30:00Z", "humanReadable": "Disk space used on data partition is 95.2%. Project: MyProject Organization: MyOrganization", "metricName": "DISK_PARTITION_SPACE_USED_DATA", "currentValue": { "number": 95.2, "units": "RAW" } }
Authenticate Webhook Requests
The Webhook Secret field stores a secret that Atlas uses solely to generate the X-MMS-Signature header for request verification. Atlas does not send the secret directly as an authentication header or bearer token.
If your webhook endpoint requires authentication, you must handle it independently using one of the following methods:
Query Parameters: Include authentication credentials in the Webhook URL as query parameters. For example:
https://example.com/webhook?token=your-auth-tokenIP Access List: Configure your webhook endpoint to accept requests only from Atlas IP addresses. This configuration ensures that only Atlas can send requests to your endpoint.
Reverse Proxy or API Gateway: Use a reverse proxy or API gateway that handles authentication before forwarding requests to your webhook endpoint.
Verify Webhook Requests
To verify that a webhook request originated from Atlas, validate the X-MMS-Signature header:
Limitations
When you use webhook integrations, consider the following limitations:
Alert Severity Not Included
The webhook payload does not include the alert severity level that you configure in Atlas. To retrieve the configured severity, make an additional call to the Atlas Administration API Get One Alert Configuration endpoint using the alertConfigId from the webhook payload.
No Manual Test Alerts
Atlas does not provide a way to trigger test alerts manually. To test your webhook endpoint, you can temporarily set up an alert with conditions that are easy to trigger, such as:
A low disk space threshold on a test cluster.
A connection count threshold that you can trigger by opening multiple connections.
A replication lag threshold on a test replica set.
After you confirm your webhook receives alerts correctly, you can delete the test alert configuration.
Firewall Configuration
If your firewall requires you to configure an IP access list, allow access from Atlas IP addresses so that Atlas can communicate with your webhook endpoint.
Troubleshoot Webhook Delivery Issues
If your webhook does not receive alerts: