Bring Your Own MongoDB Atlas

Connect your own MongoDB Atlas cluster as the storage backend for a HostWebhook Vector Store. Chunks live in your cluster — they don't count against your plan's vector quota, and your documents never leave your infrastructure.

When to use this

Pick this backend when:

• Compliance / data residency — your contracts forbid storing customer documents on shared infrastructure.
• Volume — you're ingesting more chunks than the managed plan covers, but don't want to upgrade to enterprise yet.
• Existing Atlas — you already run an Atlas cluster with Vector Search enabled and want to consolidate.

For everything else, the managed HostWebhook (managed) backend is faster to set up, zero-config, and the index is provisioned for you.

Prerequisites

• A MongoDB Atlas cluster with Vector Search enabled. Available on every Atlas tier including the free M0 (the limits on M0 are dataset size and concurrent search nodes, not feature access). M10+ recommended for production workloads with steady query volume.
• A database user with readWrite on the target collection.
• Network access from HostWebhook's outbound IPs to your cluster — see Network access below.
• The connection string in mongodb+srv:// form, including username + password.

Network access

Atlas refuses connections from any IP that isn't in its IP Access List. You have three options for letting HostWebhook through, in order of recommendation:

Option 1 — Allowlist HostWebhook's static egress IP (recommended)

Every outbound MongoDB connection from HostWebhook exits through a single static IP. The exact value is shown inline when you create a MongoDB credential — go to Settings → Credentials → New Credential → Type: MongoDB and the banner above the connection string field has the current IP plus a copy button.

Add it to your Atlas Network Access → IP Access List with a /32 mask. Only HostWebhook will be able to reach your cluster.

Option 2 — Allow 0.0.0.0/0 (simplest, less secure)

Atlas accepts 0.0.0.0/0 as a valid CIDR; combined with username+password authentication this is the default setup that most SaaS-to-Atlas integrations use today (n8n Cloud, Make, Zapier all require it). Authentication still gates access — opening the IP doesn't mean “anyone can read,” it means “anyone can attempt to authenticate.”

Acceptable for development and most production workloads. Not acceptable if your compliance team requires explicit IP allowlisting (in which case use Option 1 or 3).

Option 3 — Atlas Private Webhook (advanced)

For maximum isolation, configure an Atlas Private Webhook (AWS PrivateLink, GCP Private Service Connect, or Azure Private Link). Traffic from HostWebhook to your cluster traverses the cloud provider's private backbone and never touches the public internet.

Requires Atlas M10+ and a matching cloud account on your side. Contact HostWebhook support to coordinate the peering — this is a paid setup on the Atlas side and currently requires manual provisioning on ours.

Step 1 — Set up the Atlas collection

Create the database and collection that HostWebhook will write into. You don't need to insert anything — the first ingest creates the documents. We recommend dedicated names so you can tell vector chunks apart from your other collections.

use vector_store
db.createCollection("documents")

Database user permissions

Create or reuse a user with at minimum readWrite@vector_store. Atlas built-in roles like Atlas admin work too but are broader than needed.

Step 2 — Create the vector search index

HostWebhook does not auto-create the Atlas Vector Search index — that requires Atlas Admin API credentials we intentionally don't ask for. You create it once in the Atlas UI.

In Atlas: navigate to your cluster → Atlas Search tab → Create Search Index → choose JSON Editor → pick the database + collection from Step 1, name the index (we'll use vec_idx_1536 as a convention — the dimension number in the name keeps it unambiguous), and paste:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    }
  ]
}

Index build typically takes 1-3 minutes for an empty collection. The UI shows STATUS: Active when it's ready.

Step 3 — Save the connection in HostWebhook

In the dashboard: Settings → Credentials → New Credential → Type: MongoDB. Paste the connection string and save:

mongodb+srv://<USER>:<PASSWORD>@<CLUSTER>.mongodb.net/<DEFAULT_DB>?retryWrites=true&w=majority

HostWebhook encrypts the connection string at rest (AES-256-GCM) and validates it before saving. If you point at a private IP, localhost, or any address in the link-local range (e.g. 169.254.x.x), the credential is rejected — this prevents misconfigured strings from targeting our internal infrastructure.

Step 4 — Create the Vector Store

Go to Settings → Vector Stores → + New Store. Fill out:

• Name — any friendly identifier (e.g. Legal Documents).
• Embedding — the provider/model whose dimensions match the index you created. Bring your own LLM credential.
• Backend — pick MongoDB Atlas (your own).
• MongoDB credential — the credential from Step 3.
• Database — vector_store (Step 1).
• Collection — documents (Step 1).
• Vector index name — vec_idx_1536 (Step 2).

Click Test connection. You should see:

✓ Connected (43ms)
Mongo 7.0.x · Vector search supported · ✓ Vector index 'vec_idx_1536' found

If the index is missing, the test result includes the JSON spec to copy-paste into the Atlas Search index creator — same as Step 2.

Ingesting and querying

Once the store is created, ingestion and querying work identically to the managed backend — through the Vector Store node, the dashboard ingest UI, the AI Node Vector Store tools, or the REST API. Chunks are written to your collection with the following document shape:

{
  "_id": ObjectId(...),
  "organizationId": ObjectId(...),
  "workspaceId": ObjectId(...) | null,
  "storeId": ObjectId(...),
  "content": "...",
  "embedding": [0.012, -0.034, ...],   // 1536-d vector
  "tokenCount": 87,
  "charCount": 412,
  "sourceDocId": "uploads/abc123",
  "sourceDocName": "policy.pdf",
  "sourceDocType": "application/pdf",
  "sourceHash": "sha256:...",
  "metadata": { ... },                 // user-supplied
  "createdAt": ISODate(...),
  "updatedAt": ISODate(...)
}

You can read these documents directly in MongoDB Compass or your own tools — they're yours. Just don't modify storeId or embedding by hand or queries will fall out of sync.

Plan quota

Chunks stored in your own cluster do NOT count against vectorStoreChunksUsed on your plan. The dashboard usage tile and the per-org cap both exclude external backends.

The same goes for the 5 MB HostWebhook-managed storage cap — the pot your organization shares between built-in AI Node memory and stores on our Atlas cluster. Bytes in your own cluster never touch it. That cap is identical on every plan, so bringing your own database is the way past it; upgrading is not.

The cap on number of vector stores still applies (a store is a store regardless of backend) so you can't spam thousands of dangling configurations.

Rotating credentials

To rotate your MongoDB password without recreating the Vector Store:

1. Update the user password in Atlas.
2. In HostWebhook: Settings → Credentials → open the MongoDB credential → click Reconnect and paste the new connection string.
3. The Vector Store automatically picks up the new credential on the next query (the encrypted blob is fetched fresh per query — there's no stale cache).
4. Optional: open the store detail page and click Re-test connection to confirm.

Troubleshooting

“Connection to localhost is not allowed” / “resolves to private IP”

The SSRF guard blocked the connection string. Cases:

• You used localhost or 127.0.0.1 — self-hosted Mongo isn't reachable from our cloud anyway. Use a public Atlas SRV hostname.
• Your custom DNS resolves to a private IP — the guard re-resolves the host and refuses if any answer falls in 10.x / 192.168.x / 172.16-31.x / 169.254.x ranges.

“Vector search NOT detected” on Test connection

The cluster is reporting capabilities that don't include Atlas Vector Search. Most common causes: self-hosted Mongo (not Atlas), Mongo Enterprise without the Search module, or an Atlas cluster on Mongo < 7.0. Upgrade the cluster to Mongo 7+ on Atlas — every tier from M0 up has Vector Search since 2024.

Test passes but queries return zero results

Most common causes:

• Wrong numDimensions in the index — the embedding model emits N floats but the index expects M. Re-create the index with the right number.
• Index still building — Atlas index builds can take minutes on large collections. Check status in the Atlas Search tab.
• storeId filter mismatch — you're querying via the wrong Vector Store. Each store is scoped by its own ObjectId in the document.

Authentication errors on connect

Atlas' SRV connection strings include the password URL-encoded. Special characters like @, :, /, ?, # in the password must be percent-escaped. Atlas' “Connect” button in the UI generates the correctly-encoded string for you.

Limitations

• No auto-index management — you create and maintain the Atlas Vector Search index. We validate it exists; we don't create or drop it.
• No backups managed by us — your cluster, your backup policy.
• Tunnel cap applies if you use one — Free 1, Pro 10, Enterprise unlimited. A BYO Mongo over a private network needs a tunnel, which counts against this. Direct-internet Atlas does not.
• Self-hosted Mongo without $vectorSearch — not supported. The collection you point at MUST be on Atlas (or Enterprise with Search Nodes) running Mongo 7+.
• No migration between backends — moving from managed to BYO (or vice versa) requires re-ingesting your source documents into a new store. Embeddings can't be transplanted across backends without re-running them.