Reverse Proxy Support

Last updated:
APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

Websites built on HubSpot's CMS automatically utilize our 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. For customers on our CMS Hub Enterprise plan, we offer reverse proxy support.

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.

What is a reverse proxy?

A reverse proxy is a type of proxy server that grabs resources from one or more servers and then returns them to the client with the appearance of it coming from the proxy server itself. An example of this would be having 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. The blog appears to be hosted from the same server as the website, however, in reality, it is coming from HubSpot's servers. 

Considerations when implementing another CDN or Reverse Proxy with HubSpot

At this time, Cloudflare cannot be used. HubSpot uses Cloudflare as its CDN and Cloudflare does not currently support multiple CDN layers.

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
Bandwith Included Additional cost
SSL Included; Automatic setup Additional cost; Manual setup
Global CDN Included ?
Automatic cache management Included No
Anti-abuse protection Included Customer-owned
24x7 monitoring Included Customer-owned
Support Included Customer-owned
IPv6 Included ?
HTTP/2 Included ?
Latency Optimal Additional network hop required

Additionally, if you proxy a subpath of your site to HubSpot, your main sitemap.xml will not include HubSpot pages unless they are manually added.

Configuring a Reverse Proxy or CDN with your HubSpot account

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.

Add your new domain to HubSpot

First, add your new domain to your HubSpot account:

  1. Go to your domain settings for your portal.
  2. Click the Connect a domain button.
  3. Select Primary or Secondary. Note: Redirect and email sending domains are not supported.
  4. Click the Connect button.
  5. Choose the type of content this domain will be used for.
  6. Click the Next button.
  7. Select your brand domain if one has already been added in the portal and click "next", then enter your new domain. We'll refer to this domain as the "destination domain" from here on.
  8. Click the Next button.
  9. Click the Next button again.
  10. If this domain is hosted with GoDaddy, click "No, I'll set it up manually" when the GoDaddy connect modal appears.
  11. If this subdomain is currently hosted externally with a valid SSL certificate in place, there will be a box on the page under step 1 which says "It looks like this domain already has an SSL certificate from another provider. Click here if you would like to pre-provision SSL to ensure that there is no downtime before your new certificate is active". Click "Click here"; a modal will appear with values for a CNAME and a TXT record which are to be created on uniquely generated hostnames. These records are necessary for hostname validation, a process which allows HubSpot's CDN to serve content to incoming requests for a domain. Once they are created, click "Verify". If these records don't verify, come back in a few minutes and try again.(If this subdomain is not hosted externally with an SSL certificate, you will need to contact HubSpot support in order to get the values for these records).
  12. Click "Back to domains" in the bottom left hand corner of the page.
  13. Find your new domain in the list of domains and click the Edit menu for that domain.
  14. Check the Set as ready for publishing checkbox and click Save.
  15. 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
00-10 sites-proxy.hscoscdn00.net
11-19 sites-proxy.hscoscdn10.net
20-29 sites-proxy.hscoscdn20.net
30-39 sites-proxy.hscoscdn30.net
40-49 sites-proxy.hscoscdn40.net
50-59 sites-proxy.hscoscdn00.net
60-69 sites-proxy.hscoscdn10.net
70-79 sites-proxy.hscoscdn20.net
80-89 sites-proxy.hscoscdn30.net
90-99 sites-proxy.hscoscdn40.net

For example, if your HubID is 123, your correct origin CNAME would be 123.sites-proxy.hscoscdn20.net.  

Configure your proxy to forward requests

Now configure your proxy to forward requests using your origin CNAME and add the following configurations:

  1. 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​.
  2. 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 and ensure requests are not falsely identified as abuse. Many services such as CloudFront maintain these headers automatically.
  3. To ensure personalized content based on location works, either pass a ​X-HubSpot-Client-IP​ header 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-For​ header, which may not have been updated by all upstream proxies.
  4. Pass a ​X-HS-Public-Host​ header with a value of your destination domain.
  5. Allow all HTTP methods.
  6. Ensure an SSL certificate is provisioned and installed for your proxy domain.
  7. Forward all query strings.
  8. Forward ​all​ other request and response headers as-is, including cookies.
  9. 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.

Confirming your configuration is correct

To confirm your configuration, visit:
https://www.[yourdomain].com/_hcms/diagnostics

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-For matches 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-HubSpot-Client-IP and ending in X-Forwarded-For in descending order of precedence. If X-HubSpot-Trust-Forwarded-For is passed, True-Client-Ip and X-Real-Ip are ignored.

Publishing content

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.