GET STARTED

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:

{
  "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. 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.).

Read this page as Markdown

66 beta testing now