Test MongoDB Atlas webhooks locally

Receive Atlas alert notifications on your laptop while you build, with a URL Atlas can reach.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A MongoDB Atlas project where you can edit integrations and alert settings

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const secret = process.env.ATLAS_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("Missing ATLAS_WEBHOOK_SECRET", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-mms-signature") ?? "";
  const expected = createHmac("sha1", secret).update(body).digest("base64");

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const state = request.headers.get("x-mms-event");
  const alert = JSON.parse(body);
  console.log(`Received Atlas ${state}: ${alert.eventTypeName}`);

  return new Response("ok", { status: 200 });
}

ATLAS_WEBHOOK_SECRET=replace-with-a-long-random-string

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

Check it worksCopy Anchor Link

When the temporary alert fires, Horizon prints one line for the request:

  POST    200  /api/webhooks/mongodb

Your app terminal prints the state and the event type name, for example:

Received Atlas alert.open: HOST_DOWN

If the line shows [401], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

• Check that ATLAS_WEBHOOK_SECRET is identical to Webhook Secret in Atlas, with no extra spaces or newline.
• Compute the HMAC over the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Restart npm run dev after you edit .env.local.
• If you changed Webhook Headers Template or Webhook Body Template, the body is no longer the default alert JSON. The handler's JSON.parse and eventTypeName read can fail.

Atlas emails you about the webhookCopy Anchor Link

Atlas emails the project owner when the webhook URL or key becomes invalid, and can eventually remove the settings. Keep the tunnel running while you test, and use -s so the URL stays the same.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the Webhook URL ends with /api/webhooks/mongodb.
• Check that the alert configuration lists the webhook as a notification.

Next stepsCopy Anchor Link

• Read MongoDB's guide to integrating with webhooks.