Using a Reverse Proxy with HubSpot
Websites built on HubSpot's CMS automatically use HubSpot's global CDN with hundreds of local points of presence. However, some customers may have an existing CDN or complex routing rules that are not possible to maintain using HubSpot's built-in CDN. If you have CMS Hub Enterprise, you can configure a reverse proxy.
Note: this service is not provided by HubSpot's support team. Customers may purchase time with a Technical Consultant for support with implementing Reverse Proxy on HubSpot or use our community forums for peer-to-peer support.
A reverse proxy is a type of proxy server that takes resources from one or more servers and then returns them to the client with the appearance of it coming from the proxy server itself. For example, you could have an existing website such as www.example.com that is not hosted on the HubSpot CMS, while also hosting a HubSpot managed blog at www.example.com/blog. Using a reverse proxy, the blog would appear to be hosted from the same server as the website when it's actually coming from HubSpot's servers.
At this time, Cloudflare cannot be used. HubSpot uses Cloudflare as its CDN and Cloudflare does not currently support multiple CDN layers.
HubSpot’s built-in CDN and all other services have multiple instances with automatic failover and recovery. If you implement a reverse proxy, we highly recommend you use multiple instances with load balancing. If all requests are routed through a single proxy node, it’s possible that requests will trip rate limiting protocols and requests will be served
403 responses until an in-browser JS challenge is completed.
Using your own CDN or reverse proxy may open up more configuration options, but it also requires significant operational know-how and maintenance. Below is a list of some considerations before you choose this route.
|Feature||HubSpot's CDN||Custom Solution|
|SSL||Included; automatic setup||Additional cost; manual setup|
|Automatic cache management||Included||No|
|Latency||Optimal||Additional network hop required|
Additionally, if you proxy a subpath of your site to HubSpot, your main sitemap.xml won't include HubSpot pages unless you manually add them.
Adding a custom reverse proxy means that users of your website will make a request to your service and then be proxied through to HubSpot’s CDN, introducing another network hop.
To set up a reverse proxy, you'll first add your domain to HubSpot:
- Go to your domain settings for your portal.
- Click Connect a domain.
- Select Primary or Secondary. Redirect and email sending domains are not supported for this feature.
- Click Connect.
- Choose the type of content this domain will be used for.
- Click Next.
- Select your brand domain if one has already been added in your account, then enter your domain. This will become the destination domain for your proxy.
- Click Next.
- Review the domain you've entered, then click Next.
- If this domain is hosted with GoDaddy, click No, I'll set it up manually when the GoDaddy connect modal appears.
- If this subdomain is currently hosted externally with a valid SSL certificate in place:
- HubSpot will display the message It looks like this domain already has an SSL certificate from another provider. Click Click here to view the CNAME and a TXT values required for hostname validation. Hostname validation will allow HubSpot's CDN to serve content to incoming requests for a domain.
- Once you've created the records in your DNS provider, click Verify. It may take up to 4 hours for HubSpot to recognize the changes made to your DNS provider and verify your hostname.
- If the subdomain is not currently hosted externally with an SSL certification, contact HubSpot support to get the values needed to create the CNAME and TXT records.
- After verifying your domain, click Back to domains in the bottom left.
- Hover over the new domain in your list of domains, then click Edit.
- Select the Set as ready for publishing checkbox and click Save.
- Your domain is now ready for proxying.
Using your HubID from the steps above, your origin CNAME will be in the following form:
<HubId>.<Suffix>. Your suffix is determined by the last two digits of your HubID.
|HubIDs ending with||Suffix|
For example, if your HubID is
123, your correct origin CNAME would be
Now configure your proxy to forward requests using your origin CNAME and add the following configurations:
- Set your proxy to perform no caching for paths originating from HubSpot. HubSpot automatically manages the content of our CDN’s cache so pages are updated automatically when content is published. Note: If the service caches responses, pages may not update for hours or days.
- Add or prepend to a
X-Forwarded-For header with the client IP address of the original requestor. This is required to differentiate clients from each other. Many services such as CloudFront maintain these headers automatically.
- To ensure personalized content based on location works, either pass a
X-Client-IPheader with a value of the end user’s IP (preferred) or pass a static header of
X-HubSpot-Trust-Forwarded-For: true. The latter will trust the
X-Forwarded-Forheader, which may not have been updated by all upstream proxies.
- Pass a
X-HS-Public-Host header with a value of your destination domain.
- Allow all HTTP methods.
- Ensure an SSL certificate is provisioned and installed for your proxy domain.
- Forward all query strings.
- Forward all other request and response headers as-is, including cookies.
- Ideally, all paths under your domain should proxy to HubSpot. If that’s not the case, then the paths
/_hcms/*, /hs/*, /hubfs/*and
/hs-fs/*must proxy so assets load properly from your domain.
To confirm your configuration, visit:
and then verify the following:
- The current time value changes on every load. This confirms that the page is not cached.
- The User-Agent is consistent with your browser.
- The Accept-Language value is consistent with your browser.
- The Cookie value is not blank.
- The Protocol is “https”.
- The leftmost IP address in
X-Forwarded-Formatches your IP address as reported by a service like https://www.whatismyip.com.
- The IP-Determined Location values are accurate to your location. These are based on the IP-related headers, starting with
X-Client-IPand ending in
X-Forwarded-Forin descending order of precedence. If
If you're seeing a
404 when going to the diagnostics URL that likely means you have an issue with your configuration.
https://[yourFullDomain]/_hcms/_worker/headers to view all the headers that HubSpot is receiving from a request through your reverse proxy.
The most important headers for proxies are:
Verify you are not sending additional/unnecessary headers, or duplicate values.
Publishing content with the HubSpot CMS should work just as if your domain was directly hosted by HubSpot. Features such as A/B tests and Content Membership that rely on cookies should work normally. When creating pages be sure to select your destination domain (if available) in the URL.
Thank you for your feedback, it means a lot to us.