Set up Integration Mode on Cloudflare Workers, Next.js or Caddy

This page shows how to connect a domain in Integration Mode on the three platforms that have a ready, open-source integration. Each one serves the redirects, short links and QR code links you manage in RedirHub from a rules file, without a redeploy for each change, and reports every redirect back to your analytics.

Before you start: the rules address and the key#

1. In the dashboard, add the domain under Hostnames and choose Connect through your own platform.
2. Pick your platform. The dashboard shows the rules address for the domain and your workspace's integration key, plus a prompt with both filled in that you can paste into an AI coding agent (Claude, Cursor, ChatGPT and others) instead of following the steps below by hand.
3. Store the key as a secret or environment variable. The rules address is not a secret, but don't publish it.

After you deploy, the first answer on /_redirhub/check connects the domain. The dashboard checks every 15 minutes, or right away with Check now.

Cloudflare Workers#

A Worker in front of your origin serves the redirects and passes every other request through. Source and full options: redirhub/cloudflare-redirects.

bashnpm install @redirhub/cloudflare-redirects

Create src/index.ts:

typescriptimport { createWorker } from '@redirhub/cloudflare-redirects'

interface Env {
  ACME_RULES_URL: string
  ACME_INTEGRATION_KEY: string
}

export default createWorker<Env>({
  settings: (env) => ({ rulesUrl: env.ACME_RULES_URL, key: env.ACME_INTEGRATION_KEY }),
})

Set a route for the hostname and the rules address in wrangler.toml (the dashboard shows the exact variable names for your domain):

tomlname = "shop-redirects"
main = "src/index.ts"
compatibility_date = "2026-11-01"
routes = [{ pattern = "shop.example.com/*", zone_name = "example.com" }]

[vars]
ACME_RULES_URL = "https://rules.example.com/…/TOKEN.txt"

Add the key as a secret and deploy:

bashnpx wrangler secret put ACME_INTEGRATION_KEY
npx wrangler deploy

• The route must cover every path of the hostname, including /_redirhub/check.
• Catch-all rules work: when your origin answers 404, the Worker redirects instead.
• 404 reports work: your origin's 404s are reported when Report 404 pages is on for the hostname.

Next.js (Vercel or self-hosted)#

The redirects run in your proxy (Next.js 16) or middleware (Next.js 15 and earlier), before your pages. Source and full options: redirhub/nextjs-redirects.

bashnpm install @redirhub/nextjs-redirects

Add the rules address and the key as environment variables (Vercel project settings, or .env.local locally). Never prefix the key with NEXT_PUBLIC_. Then create proxy.ts (or middleware.ts with export function middleware on Next.js 15 and earlier):

typescriptimport type { NextFetchEvent, NextRequest } from 'next/server'
import { createProxy } from '@redirhub/nextjs-redirects'

const redirects = createProxy({
  rulesUrl: process.env.ACME_RULES_URL,
  key: process.env.ACME_INTEGRATION_KEY,
})

export async function proxy(request: NextRequest, event: NextFetchEvent) {
  const answer = await redirects(request, event)
  if (answer) return answer
  // … your own proxy logic, or nothing
}

• Call it first, before rewrites and locale handling.
• The matcher must let /_redirhub/check and the paths you redirect through. A matcher that skips every path with a dot also skips rules such as /old.html.
• Redirects in next.config run before the proxy, so they can shadow your rules.
• The proxy runs before the page and never sees whether your app answers 404, so catch-all rules and 404 reports are not served there. To add both, use createRedirects() and its afterSite() where you do see the final answer, for example in a route handler (see the README).

Caddy#

A Caddy v2 module for your own servers. One Caddy can serve all your integration domains from one Workspace rules address, and it can issue HTTPS certificates on demand only for the hostnames in your rules. Source and full options: redirhub/caddy-redirects.

Build Caddy with the module:

bashxcaddy build --with github.com/redirhub/caddy-redirects

For Caddy, copy the Workspace rules address from the Integration key panel instead of the per-domain address. Then add the handler to your Caddyfile:

text{
	on_demand_tls {
		permission redirects
	}
}

https:// {
	tls {
		on_demand
	}
	redirects {
		rules_url https://rules.rediredge.com/abc123/TOKEN.txt
		key {env.REDIRHUB_INTEGRATION_KEY}
	}
	reverse_proxy localhost:8080
}

• Set REDIRHUB_INTEGRATION_KEY in Caddy's environment and reload Caddy.
• Changes arrive within a second or two by push, with polling as the fallback. The last good rules are kept on disk, so a restart redirects at once.
• Catch-all rules work when the rest of the route answers 404. Behind try_files with a fallback (a single-page app), the site never answers 404, so the catch-all never fires.
• 404 reports follow each hostname's Report 404 pages switch. With report_404 all, every 404 of the site block is reported, even for hostnames you haven't added to RedirHub.

After you deploy#

• Open the domain under Hostnames and click Check now. The status should change to Connected.
• Test a rule in a private window or with curl -I.
• If the domain stays on Waiting or a redirect doesn't fire, see Troubleshooting Integration Mode.