# MongoDB Atlas Webhooks

## When to Use This Skill

* How do I receive MongoDB Atlas alert webhooks?
* How do I verify the Atlas `X-MMS-Signature` webhook header?
* Why does my Atlas webhook signature verification fail (base64 vs hex, SHA-1, raw body)?
* How do I handle `OUTSIDE_METRIC_THRESHOLD` or `HOST_DOWN` alerts and `OPEN` / `CLOSED` status?
* What do I do if my Atlas webhook has no secret (no signature header)?

## Verification (core)

Atlas signs alert webhooks only when you set a **Webhook Secret**. The `X-MMS-Signature` header is the **base64-encoded HMAC-SHA1** of the **raw request body**, keyed with the secret as a plain string (not decoded). There is no timestamp and no prefix. Without a secret the header is absent, so reject unsigned requests if you expect signing.

```javascript
const crypto = require('crypto');

function verifyAtlasSignature(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  const expected = crypto.createHmac('sha1', secret).update(rawBody).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // length mismatch
  }
}

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mongodb-atlas-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mongodb-atlas-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mongodb-atlas-webhooks/examples/fastapi/).

## Common Event Types

Atlas alert payloads share the Administration API Alerts resource shape. Dispatch on `eventTypeName`; `status` is `OPEN` or `CLOSED` (the docs give these as examples).

| `eventTypeName` | Description |
| --- | --- |
| `OUTSIDE_METRIC_THRESHOLD` | A metric (see `metricName`, `currentValue`) crossed its alert threshold |
| `HOST_DOWN` | A host is down |

The full list of alert event types lives in the Atlas Administration API alerts documentation. The `X-MMS-Event` header carries the alert state: `alert.open`, `alert.close`, `alert.update`, `alert.acknowledge`, `alert.cancel`, `alert.inform`.

> **For payload fields and more**, see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mongodb-atlas-webhooks/references/overview.md).

## Important Headers

| Header | Description |
| --- | --- |
| `X-MMS-Signature` | Base64 HMAC-SHA1 of the raw body; only sent when a Webhook Secret is set |
| `X-MMS-Event` | Alert state (`alert.open`, `alert.close`, ...) |

## Authentication

The secret is **not** sent as a credential; it is only used for the signature. If you cannot sign, authenticate another way: a token in the URL query string, an [Atlas IP access list](https://www.mongodb.com/docs/atlas/setup-cluster-security/#std-label-atlas-add-inbound-ips), or a reverse proxy / API gateway.

## Environment Variables

```bash
MONGODB_ATLAS_WEBHOOK_SECRET=your_webhook_secret   # Project Settings → Integrations → Webhook Settings

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 mongodb-atlas --path /webhooks/mongodb-atlas

```

Atlas has no test button; create a temporary alert with an easy-to-trigger condition, then delete it.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mongodb-atlas-webhooks/references/overview.md) - Alert webhooks, payload fields, headers, delivery
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mongodb-atlas-webhooks/references/setup.md) - Configure Webhook Settings and alert notifications
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mongodb-atlas-webhooks/references/verification.md) - X-MMS-Signature details and debugging