> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Integrate with Webhooks

You can configure Atlas to send alert notifications to a webhook endpoint as HTTP (HyperText Transport Protocol) 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`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project.

## Configure a Webhook Integration

1. 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](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsettings%2FgroupSettings) page displays.

2. In Atlas, go to the Project Integrations page.

   Click the Integrations tab.

   The [Project Integrations](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fintegrations) page displays.

3. Click Configure for Webhook Settings.

4. Enter the webhook URL.

   In the Webhook URL field, enter the endpoint URL where Atlas should send alert notifications.

5. (Optional) Enter a webhook secret.

   In the Webhook Secret field, enter a secret key. Atlas uses this secret to generate the `X-MMS-Signature` header for request verification.

6. (Optional) Customize webhook templates.

   You can customize the request headers and body content using FreeMarker templates:

   In the Webhook Headers Template field, enter a FreeMarker template to customize the HTTP (HyperText Transport Protocol) headers sent with webhook requests.

   In the Webhook Body Template field, enter a FreeMarker template to customize the request body structure.

   If you configure templates and later view or edit the webhook integration, the templates appear redacted with `******`. You can overwrite the redacted templates with new values.

   Atlas validates FreeMarker syntax when you save the configuration. If your template contains invalid syntax, the form displays an inline validation error.

7. Click Save.

To send alerts to your webhook, configure alert notifications. To learn more, see [Configure Alert Settings.](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-configure-alerts)

## Request Headers

Atlas includes the following HTTP (HyperText Transport Protocol) headers with each webhook request:

| Header | Description |
| --- | --- |
| `X-MMS-Event` | Indicates the alert state. Possible values: `alert.open`: Atlas just opened the alert.; `alert.close`: Atlas resolved the alert.; `alert.update`: A previously opened alert is still open.; `alert.acknowledge`: A user acknowledged the alert.; `alert.cancel`: The alert became invalid; Atlas canceled it.; `alert.inform`: Represents an informational alert, which is a point-in-time event, such as "Primary Elected." |
| `X-MMS-Signature` | (Optional) If you specify a secret in the Webhook Secret field, Atlas includes this header. Contains the Base64-encoded HMAC (hash-based message authentication code)-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 (Javascript Object Notation) document that uses the same format as the Atlas Administration API [Alerts resource](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listgroupalerts). 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`).

- `severity`: Severity of the alert. Atlas sets this value when the alert opens. To learn how Atlas determines severity, see [Severity Levels.](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-atlas-alert-severity-levels)

- `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](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listgroupalerts) documentation.

The [Return All Project Alerts](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listgroupalerts) and [Return One Alert](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getgroupalert) endpoints also return the resolved `severity` for each alert. This value matches the severity that Atlas includes in webhook, PagerDuty, and Opsgenie notification payloads.

### Example Webhook Payload

The following example shows a sample webhook payload for a disk space alert:

```json
{
  "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-token`

- **IP Access List**: Configure your webhook endpoint to accept requests only from [Atlas IP addresses](https://www.mongodb.com/docs/atlas/setup-cluster-security.md#std-label-atlas-add-inbound-ips). 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:

1. Retrieve the `X-MMS-Signature` header value from the incoming request.

2. Calculate the Base64-encoded HMAC (hash-based message authentication code)-SHA-1 signature of the request body using your webhook secret.

3. Compare your calculated signature with the `X-MMS-Signature` header value.

   If they match, the request is authentic.

## Limitations

When you use webhook integrations, consider the following limitation:

### 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](https://www.mongodb.com/docs/atlas/setup-cluster-security.md#std-label-atlas-add-inbound-ips) so that Atlas can communicate with your webhook endpoint.

## Troubleshoot Webhook Delivery Issues

If your webhook does not receive alerts:

1. Verify that the webhook URL is correct and accessible from the Internet.

2. Check that your firewall allows incoming requests from [Atlas IP addresses](https://www.mongodb.com/docs/atlas/setup-cluster-security.md#std-label-atlas-add-inbound-ips).

3. Ensure your webhook endpoint returns a 2xx HTTP status code.

   Atlas considers other status codes as failures.

4. Review your alert configuration to ensure alerts are enabled and the webhook is selected as a notification method.

5. Check the Activity Feed in the Atlas UI for any webhook delivery errors.