Running the front end on Cloudflare

PLUS A front end that reads the headless interface can run as a Cloudflare Worker: Cloudflare builds the website on every change in the Git repository and delivers it worldwide. WP-ImmoMakler remains the data source and reports after every import that the website should be rebuilt. This page describes what you set up in WordPress and at Cloudflare for this. The examples refer to an Astro front end with pre-rendered pages and server-side routes for search and forms, as implemented by the 49heroes Astro starter.

What Cloudflare costs

The free Workers plan has these limits:

Free plan	Limit
Requests generated on the server (search, forms, watch list, search alert page, webhook)	100,000 per day
Compute time per request	10 ms
Pre-rendered pages, images, scripts	free and unlimited
Builds from Git	3,000 minutes per month, one at a time

Detail pages, category pages and content pages are generated at build time and do not count as requests. The time spent waiting for WordPress does not count towards compute time, only the generation of the page. You can see the compute times at Cloudflare under Observability of the Worker. The paid plan starts at 5 US dollars per month; the current terms are in Cloudflare’s pricing overview.

Requirements

• WP-ImmoMakler version 5.71.0 or later in a PLUS edition
• Your WordPress website is reachable from the internet and has a valid certificate. A Worker does not fetch private addresses or pages with a self-signed certificate.
• A Cloudflare account and the Git repository of your front end on GitHub or GitLab

Setting up in WordPress

In the back end of your website (wp-admin) under WP-ImmoMakler → Integrations → Headless:

1. Enable the interface

   Enable Enable headless interface and save. Check that the interface responds:

   curl -s https://www.your-domain.com/wp-json/immomakler-headless/v1/site

   The response begins with {"api_version":. If WordPress responds with rest_no_route, the interface is still switched off or an object cache is holding the old settings; clear the cache in that case.

2. Note the credentials

   Under Access credentials, note the API key, and under Webhook secret and status the webhook secret. You will store both at Cloudflare later.

3. Enter the address of your front end

   Under Address of your front end, enter the address of the Worker, for example https://your-project.your-account.workers.dev, later your own domain. The links of the interface, of the emails for enquiries and of the search alerts then point to the front end. You learn the address at Cloudflare after the first build; you can leave the field empty until then.

4. Enter trusted proxy addresses

   A Worker sends forms on behalf of the visitors and has no fixed address. Under Trusted proxy addresses, enter the address ranges that Cloudflare publishes at cloudflare.com/ips, one per line in CIDR notation, for example 173.245.48.0/20 or 2400:cb00::/32. Without these ranges, the limit on requests per hour counts all visitors of your front end together. More on this under Forms via the headless interface.

Setting up at Cloudflare

1. Connect the repository

   In the Cloudflare dashboard, open Workers & Pages → Create → Import a repository and select the repository of your front end. For a private repository of an organisation, Cloudflare’s GitHub app must have access to it; the owners of the organisation approve this at GitHub under Settings → GitHub Apps.

2. Configure the build

   Choose a project name made of lowercase letters, digits and hyphens; it becomes part of the address. For the Astro starter, the build command is npm run build and the deploy command is npx wrangler deploy. You can leave Preview builds switched off as long as you only work in the main branch; every preview needs its own variables and secrets.

3. Enter build variables

   The variables under Advanced settings → Variables apply to the build only. Values that are written into the website at build time belong here; if you change one, a new build is needed. For the Astro starter:

   Name	Value
   DEPLOY_TARGET	cloudflare
   IMMOMAKLER_API_URL	https://www.your-domain.com/wp-json/immomakler-headless/v1
   PUBLIC_SITE_URL	the address of the Worker, after the first build

   Do not leave a row with an empty value, otherwise the Deploy button does not respond. The build only needs the API key if Require an API key for read requests too is enabled.

4. Start the first build and adopt the address

   Click Deploy. After the build, the overview of the Worker shows its address, https://<project name>.<account>.workers.dev; the subdomain of your account is also shown in the overview under Workers & Pages. Enter the address as PUBLIC_SITE_URL under Settings → Build → Variables and secrets and in WordPress as Address of your front end, and restart the build (Retry build).

5. Store secrets

   Under Settings → Runtime variables and secrets, create the values in the Production section that the Worker reads on every request. Click Add variable each time and choose the entry Secret as the Type:

   Name	Value
   IMMOMAKLER_API_KEY	the API key from the Headless tab
   IMMOMAKLER_WEBHOOK_SECRET	the webhook secret from the same tab
   BUILD_HOOK_URL	the address of the deploy hook from the next section

   Secrets take effect without a new build. A build variable is not available at runtime: an API key that is only stored there is missing for the forms.

   Caution

   Also create BUILD_HOOK_URL as a Secret, not as a Variable. Cloudflare replaces plain variables on every deploy with those from the repository’s Wrangler configuration, so the address is missing after the next push. Do not follow the hint to adopt the variable into the Wrangler configuration: the address would then be in the repository, and anyone with read access could start builds.

Rebuilding after every import

WP-ImmoMakler reports changes to the front end, and the front end starts a build at Cloudflare:

1. Create a deploy hook

   At Cloudflare under Settings → Builds → Deploy Hooks, create a hook for the main branch and copy its address. Anyone who knows this address can start builds; treat it like a password. Store it as the secret BUILD_HOOK_URL. If the address has fallen into the wrong hands, delete the hook, create a new one and replace the secret.

2. Enable the webhook in WordPress

   Under Send webhook, enable sending and enter under Webhook URL the address that your front end provides for notifications, for the Astro starter https://<address of the Worker>/api/revalidate/, with the trailing slash. The Wait time (seconds) combines the changes of one import into a single build.

3. Check the connection

   Click Send test message. The settings report whether the message was delivered; a test message does not trigger a build. To check the whole chain, change and save a property: after the wait time, a new build appears at Cloudflare under Deployments.

How the message is structured and how your front end verifies the signature is described in Webhook, links and redirect.

Tip

In a Worker, the Node module node:crypto is only available with the compatibility flag nodejs_compat. With Web Crypto you verify the signature without this flag, in Node and in Workers alike:

const encoder = new TextEncoder();
const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
const digest = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(`${timestamp}.${rawBody}`)));
const expected = 'sha256=' + Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');

let difference = expected.length ^ signatureHeader.length;
for (let i = 0; i < Math.min(expected.length, signatureHeader.length); i++) {
  difference |= expected.charCodeAt(i) ^ signatureHeader.charCodeAt(i);
}
const valid = difference === 0;

Your own domain

Add your domain at Cloudflare under Settings → Domains & Routes. Then change the address everywhere: PUBLIC_SITE_URL at Cloudflare (with a new build), Address of your front end and Webhook URL in WordPress. Also enter the domain as an allowed domain with your captcha provider, and under Allowed origins if visitors’ browsers call WordPress directly, for example for the address suggestions of the radius search.

Frequently asked questions

Is it free to run?

On the free plan you pay nothing as long as the website stays within the limits in What Cloudflare costs. Pre-rendered pages do not count.

Can I build the website locally and upload it via SFTP?

Only in part. The pre-rendered pages are simple files that any web space can serve. The search with filters, the forms, the watch list, the search alert page and the notification after imports, however, need a server that answers requests. There are two ways to do this: a hosting plan that runs Node.js applications, or a front end that sends search and forms directly from the browser to the interface; the form routes accept such requests from the allowed origins. With an uploaded build, new properties only appear after the next build and upload.

Do I need preview builds?

No. Preview builds create a separate preview for every branch except the main branch. Every preview needs its own variables and secrets and has its own address, which is not entered in WordPress as an allowed origin.

Where do I enter which variable?

Values that are written into the website at build time (DEPLOY_TARGET, IMMOMAKLER_API_URL, PUBLIC_SITE_URL) belong to the build variables, under Advanced settings → Variables when creating the project, later under Settings → Build → Variables and secrets. Values that the Worker reads on every request (IMMOMAKLER_API_KEY, IMMOMAKLER_WEBHOOK_SECRET, BUILD_HOOK_URL) are created as secrets under Settings → Runtime variables and secrets after the project has been created.

How do I find out the address of the Worker?

It is made up of the project name and the workers.dev subdomain of your account. The subdomain is shown in the overview under Workers & Pages, the full address in the overview of the Worker after the first build.

Troubleshooting

What you see	Cause	Solution
The Deploy button does not respond	a variable with an empty value or an invalid field	remove empty rows, look for fields marked red
The build aborts with GET /site failed with 404 Es wurde keine Route gefunden	the interface is switched off in WordPress	Enable the interface
The build aborts with a certificate or connection error	WordPress is not publicly reachable	use a publicly reachable WordPress website with a valid certificate
Forms fail, the spam token responds with 502, WordPress reports 403	IMMOMAKLER_API_KEY is missing at runtime, is only stored in the build variables or differs from the API key in WordPress	store it as a secret under Runtime variables and secrets, copy the current API key
Log: “Headless webhook address redirects; followed it once”	the Webhook URL lacks the trailing slash, the front end redirects; WP-ImmoMakler follows the redirect on the same domain	enter the address given under to in the log, for example …/api/revalidate/
Log: “Headless webhook refused by the front end” with status 301, 302, 307 or 308	the webhook URL redirects to another domain or with a type of redirect that WP-ImmoMakler does not follow	enter the final address
Test message or log: status 503	IMMOMAKLER_WEBHOOK_SECRET is missing	store it as a secret
Test message: status 401	the secret differs from the one in WordPress	copy the secret again
Imports do not rebuild the website	BUILD_HOOK_URL is missing or Send webhook is off	set up the deploy hook and the webhook
Imports only rebuild the website until the next push	BUILD_HOOK_URL was created as a Variable instead of a Secret, the next deploy removed it	create it again as a secret
The language switcher or emails lead to WordPress	Address of your front end is empty	enter the address, rebuild
Canonical links point to localhost	PUBLIC_SITE_URL is missing	enter the build variable, rebuild

You might also be interested in

• Headless Mode with Your Own Front End
• Webhook, links and redirect
• Forms via the headless interface
• Headless interface API reference