MongoDB Atlas Webhooks Skill

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.

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/, examples/nextjs/, 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).

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.

Important Headers

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, or a reverse proxy / API gateway.

Environment Variables

MONGODB_ATLAS_WEBHOOK_SECRET=your_webhook_secret   # Project Settings → Integrations → Webhook Settings

Local Development

# 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 - Alert webhooks, payload fields, headers, delivery
• references/setup.md - Configure Webhook Settings and alert notifications
• references/verification.md - X-MMS-Signature details and debugging