You can configure Cloud Manager to send alert notifications to a webhook endpoint as HTTP POST requests for programmatic processing. Webhooks allow you to integrate Cloud Manager alerts with custom monitoring systems, incident management platforms, or automation workflows.
Required Access
To integrate Cloud Manager with webhooks, you must have Project Monitoring Admin access to the project.
Configure a Webhook Integration
In MongoDB Cloud Manager, 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 Project Settings.
The Project Settings page displays.
Go to the Project Integrations page.
In the sidebar, click Integrations under the Settings heading.
The Project Integrations page displays.
To send alerts to your webhook, configure alert notifications. To learn more, see Configure Alert Settings.
Request Headers
Cloud Manager includes the following HTTP headers with each webhook request:
Cloud Manager adds a request header called X-MMS-Event to distinguish between various alert states. The possible values for this header are:
| The alert was just opened. |
| The alert was resolved. |
| A previously opened alert is still open. |
| The alert was acknowledged. |
| The alert became invalid and was canceled. |
| Represents an informational alert, which is a point-in-time event, such as "Primary Elected." |
If you specify a key in the Webhook Secret field, MongoDB Cloud Manager adds the X-MMS-Signature request header. This header contains the base64-encoded HMAC-SHA-1 signature of the request body. MongoDB Cloud Manager creates the signature using the provided secret.
Request Body
The request body contains a JSON document that uses the same format as the Cloud Manager 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 (for example,OPEN,CLOSED).humanReadable: Human-readable description of the alert.
For a complete list of fields, refer to the Get One Alert endpoint documentation.
Example Webhook Payload
The following example shows a sample webhook payload for a metric threshold 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%.", "metricName": "DISK_PARTITION_SPACE_USED_DATA", "currentValue": { "number": 95.2, "units": "RAW" } }
Customize Webhook Templates
You can customize the webhook request headers and body content by setting the webhookHeadersTemplate and webhookBodyTemplate fields on the webhook notification. Each template supports ${field} interpolation: Cloud Manager replaces each ${field} placeholder with the value of the matching field from the alert document when it sends the notification.
You can interpolate any field that the alert document returns, such as ${eventTypeName}, ${clusterName}, ${status}, and ${created}. For the complete list of fields you can interpolate, see the response fields for the Get One Alert endpoint.
For example, the body template {"event": "${eventTypeName}", "cluster": "${clusterName}"} renders each placeholder with its alert value before Cloud Manager sends the request.
The rendered body must be valid JSON and is sent with the Content-Type: application/json header. The rendered headers must form a JSON object that maps each header name to its value. Cloud Manager doesn't expose the webhook secret or signature header to templates, and redacts both template fields in API responses.
If a template fails to render, exceeds the size limit, or produces invalid output, Cloud Manager sends its default payload and headers instead and still delivers the notification.
To preview the rendered output before you save the alert, click the Post test message to webhook button, which renders your templates against sample alert data.
Authenticate Webhook Requests
The Webhook Secret field stores a secret that Cloud Manager uses solely to generate the X-MMS-Signature header for request verification. Cloud Manager 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 Cloud Manager IP addresses. This configuration ensures that only Cloud Manager 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 Cloud Manager, 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 Cloud Manager. To retrieve the configured severity, make an additional call to the Get One Alert Configuration endpoint using the alertConfigId from the webhook payload.
No Manual Test Alerts
Cloud Manager 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 deployment.
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 Cloud Manager IP addresses so that Cloud Manager can communicate with your webhook endpoint.
Troubleshoot Webhook Delivery Issues
If your webhook does not receive alerts: