# Connect wizard

> The one-stop tool that figures out which delivery mechanism fits your stack and walks you through wiring it up. Five architectures, one workflow.

# Connect-destination wizard

The Connect wizard is the fastest way to point Mentionwell at your site. It picks the right delivery mode for your stack, generates a copy-paste receiver (if you need one), shows your per-site secrets, and tests the connection live before you save.

## Where to open it

Mentionwell dashboard → pick your site → **Integration** → **Connect with guided wizard**.

If the site has never been connected, the button says **Connect with guided wizard**. Once connected, it switches to **Reconfigure delivery**. The wizard is also the source of truth for your **webhook signing secret** and **Reader API key** — they're shown on the **Setup** step with copy buttons.

## How it picks for you

The wizard asks one question: *what does your site look like?* You pick the closest match from five architectures.

| Architecture | Underlying delivery mode | Best for | Setup steps |
|---|---|---|---|
| **Static site (Vercel / Netlify / Cloudflare Pages)** | `webhook_push` + deploy hook | Astro, Next.js SSG, Hugo, 11ty, Jekyll, Gatsby — anything that rebuilds on each publish | Paste a receiver file + your deploy hook URL + two env vars |
| **Next.js with on-demand revalidation (ISR)** | `webhook_push` (no deploy hook) | Next.js App Router or Pages Router using `revalidatePath()` / `revalidateTag()` | Paste a single revalidate route + one env var |
| **Dynamic site (SSR / on-request rendering)** | `api_reader` | Next.js full SSR, Remix, Rails, Laravel, Django, Express + SSR | **No receiver code.** Just add three env vars |
| **Repo-driven content (Git is the CMS)** | `github_mdx` | Astro content collections, Next.js MDX in `/content`, Hugo content/, Docusaurus | Paste a GitHub repo + token. Mentionwell commits MDX files directly |
| **WordPress / Ghost / Sanity / Webflow / custom CMS** | `direct_api` | Articles live in a third-party CMS | Pick your CMS + paste its create-post endpoint URL |

## Step 1 — pick architecture

You see five tiles, each with examples of the frameworks/hosts that fit. Pick one. The wizard remembers your choice across saves so you can reconfigure later.

## Step 2 — set up

The form on this step depends on what you picked. For `static_deploy_hook` you'll be asked for:

- **Webhook receiver URL** — the URL on your site where the receiver lives, e.g. `https://your-site.com/api/mentionwell-revalidate`.
- **Deploy hook URL** — get this from your host:
  - **Vercel**: Project Settings → Git → Deploy Hooks → create one for the main branch.
  - **Netlify**: Site Settings → Build & deploy → Build hooks.
  - **Cloudflare Pages**: Settings → Builds & deployments → Deploy hooks.

The wizard then shows you:

1. A **copy-paste receiver file** with your secrets baked in. Drop it in your repo at the filename shown.
2. The **env vars** you need to set on your hosting provider (with copy buttons).
3. Your **per-site Reader API key and webhook secret** — these never change for your site, so once they're saved on the destination they're saved forever.

For `dynamic_reader`, step 2 is just the env-var list — no code to paste.

For `github_mdx`, you provide a repo (`owner/name`), an optional branch (defaults to `main`) and content path (defaults to `src/content/blog`), and a GitHub token with `contents:write`.

For `cms_adapter`, you pick your CMS and provide the create-post endpoint URL. WordPress: `/wp-json/wp/v2/posts`. Ghost: `/ghost/api/admin/posts`. Custom: any endpoint you control.

## Step 3 — test & save

Hit **Save & test**. Mentionwell:

1. Writes your configuration to the database.
2. Fires a real signed request at your destination:
   - For webhook architectures: sends a `post.test` event (also stamps `X-MentionWell-Test: 1`) to your publish endpoint. Your receiver must respond `2xx` — and ignore the test post.
   - For `github_mdx`: hits the GitHub API to confirm the token can see the repo. No write happens during the test.
   - For `dynamic_reader`: echoes the Reader API key so you can confirm it matches what you've set in your env.

You see the exact HTTP status, response body (first 500 chars), and a human-readable diagnosis if it fails. The most common failure is **HTTP 401 from your receiver** — that means `MENTIONWELL_WEBHOOK_SECRET` on your destination doesn't match the secret Mentionwell signs with. Re-copy it from the wizard's Setup step.

## What gets saved

Inside Mentionwell, the wizard updates `sites.delivery_config`:

```jsonc
{
  "mode": "webhook_push",            // or api_reader / github_mdx / direct_api
  "architecture": "static_deploy_hook",
  "publishEndpoint": "https://your-site.com/api/mentionwell-revalidate",
  "deployHookUrl": "https://api.vercel.com/v1/integrations/deploy/...",
  "autoPushPublishedPosts": true,    // turned on when the test passes
  // For github_mdx: githubRepo, githubBranch, githubContentPath, githubToken
  // For cms_adapter: cmsAdapter
  "destinationBaseUrl": "https://your-site.com"
}
```

After this, every publish on this site goes through the chosen architecture automatically. There's no manual delivery toggle to flip again.

## Want to do it without the wizard?

You can — the wizard just wraps these endpoints, documented in [API reference → Dashboard endpoints](/docs/api#dashboard--integration-endpoints-authenticated). Or hand-edit the dashboard's Manual setup tab on the Integration page. The wizard handles 99% of cases; manual exists for the 1% with unusual requirements (split deploys, multi-environment receivers, etc.).


---

Canonical URL: https://mentionwell.com/docs/connect-wizard
Live HTML version: https://mentionwell.com/docs/connect-wizard
Section: Get started
Site index for AI ingestion: https://mentionwell.com/llms.txt
Full reference: https://mentionwell.com/llms-full.txt