Set up a reverse proxy with HubSpot

• Configure the proxy in your external environment.
• Confirm that the configuration is correct.
• Added the domain to HubSpot to enable content publishing.

​

Before you begin

​

General prerequisites

• Confirm a reverse proxy is the right solution for your use case.
• Understand how reverse proxies work with HubSpot.
• Review the considerations and trade-offs.
• Verify you meet the prerequisites, including having a CDN or distributed computing environment.

​

Cloudflare prerequisites

​

Check for Cloudflare zone holds

1. Log in to your Cloudflare account.
2. Navigate to the zone for your domain.
3. Go to Overview or check your account-level security settings.
4. Look for the Zone Hold setting. If it is enabled, you must disable it before proceeding with the reverse proxy setup.

​

Understand hostname verification with Cloudflare O2O

• Hostname pre-validation via TXT or HTTP token is not supported for O2O custom hostnames. Cloudflare detects that the domain is already on their network and requires DNS-based activation instead.
• The hostname will only be verified once a proxied (orange-clouded) CNAME record is added pointing to the appropriate HubSpot zone.
• If your domain is currently hosted elsewhere and you attempt to use a reverse proxy like nginx or Apache to forward requests to HubSpot’s zone, this will not work and will result in an error.
• The only way to activate the hostname is to add the orange-clouded CNAME record pointing to your HubSpot zone.

​

General instructions

​

Configure the proxy

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 that 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. Many services such as CloudFront maintain these headers automatically.
3. To ensure personalized content based on location works, pass a static header of X-HubSpot-Trust-Forwarded-For: true​. This 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 following paths must proxy so assets load properly from your domain:
   • /_hcms/*
   • /hs/*
   • /hubfs/*
   • /hs-fs/hubfs/*
   • /hs-fs/*
   • /cs/c/*
   • /e3t/*
   • /events/*

​

Confirm the configuration is correct

• In your HubSpot account, click the settings icon in the main navigation bar.
• In the left sidebar menu, navigate to Website > Domains & URLs.
• Next to the domain you are using for your reverse proxy, click the Edit dropdown menu and select Verify Reverse Proxy Connection.
• Click any category that is labeled as Failed to view recommendations for fixing the issue.
• Once you’ve implemented your fixes, click Refresh test to check your configuration again.

• 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 Accept-Encoding header is *. This ensures that responses are compressed.
• 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 in X-Forwarded-For.

​

Add the domain to HubSpot

• In your HubSpot account, navigate to your domain settings.
• Click Connect a domain.
• Select Primary or Secondary. Redirect and email sending domains are not supported for this feature.
• Click to toggle the Connect with HubSpot’s built-in content delivery network (CDN) switch off, then click Connect.
• Select the content type you’ll be hosting on the domain, then click Next.
• Enter the brand domain. For example, for www.website.com, you would enter website.com. This domain must match the domain being requested through your reverse proxy.
• Enter the subdomain that you’ll be hosting content on. The subdomain needs to match the subdomain for the externally hosted domain. Then click Next.
• Review the domain you’ve entered, then click Next.
• Next, verify your domain so that HubSpot can confirm your domain ownership and allow content publishing:
  • In your DNS provider, create the records using the provided values.
  • In HubSpot, click Verify. It can take up to 4 hours for HubSpot to recognize changes made to your DNS provider and verify your hostname.

​

Provider-specific instructions

​

Set up a reverse proxy in Amazon CloudFront

• Log in to your Amazon CloudFront account.
• In the left sidebar, navigate to Distributions.
• If you’re starting from scratch, you’ll first need to create a new distribution by clicking Create Distribution. Alternatively, you can edit an existing distribution or skip to the origin and behaviors setup steps.
  • On the General tab, click Edit.
  • In the Alternate Domain Names (CNAMEs) field, add the domain, including the subdomain. This must match the domain you added to HubSpot.
  • Confirm your changes by clicking Yes, Edit. You’ll then be directed back to the General tab where your domain should now be listed next to Alternate Domain Names (CNAMEs).
  • You’ll also need to create a new CNAME record in your DNS provider using the value from the Domain Name field. This value should look something like <value>.cloudfront.net.

• Next, set up a new origin:
  • Click the Origins and Origin Groups tab.
  • Click Create Origin, then set up your origin:
    • In the Origin domain field, enter the <HubID>.<suffix> domain value from the table above. This value should look something like 123.sites-proxy.hscoscdn20.net.
    • Under Add custom header, click Add header. Then, add the following header details:
      • To ensure personalized content based on location works, either pass a X-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.
      • Pass a X-HS-Public-Host header with a value of your destination domain.
  • Click Create to save your changes.
• Then, set up cache behaviors for the page paths you’ll be hosting HubSpot content on:
  • Click the Behaviors tab.
  • Click Create Behavior.
  • In the Path pattern field, enter the URL path of the page that your HubSpot content is hosted on. This can be a path to a specific page, or a flexible URL such as a wildcard. Learn more about path patterns.
  • Click the Origin and Origin Groups field, then select the origin you created earlier.
  • Click Save changes.

​

Set up a reverse proxy using nginx

location ~ ^(/|/some-other-path) {
    proxy_set_header Host $http_host;
    proxy_set_header X-HS-Public-Host www.example.com;
    proxy_pass_request_headers on;
    proxy_set_header X-HubSpot-Trust-Forwarded-For true;
    proxy_pass https://2XX93.sites-proxy.hscoscdnXX.net;
    proxy_ssl_name www.example.com;
    proxy_ssl_server_name on;
    proxy_set_header   X-Real-IP $proxy_protocol_addr;
    proxy_set_header   X-Forwarded-Proto  $scheme;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   X-HubSpot-Client-IP $proxy_protocol_addr;
  }

location ~ ^(/hs|/_hcms|/hubfs|/hs-fs|/cs/c|/e3t|/events) {
    proxy_set_header Host $http_host;
    proxy_set_header X-HS-Public-Host www.example.com;
    proxy_pass_request_headers on;
    proxy_set_header X-HubSpot-Trust-Forwarded-For true;
    proxy_pass https://2XX93.sites-proxy.hscoscdnXX.net;
    proxy_ssl_name www.example.com;
    proxy_ssl_server_name on;
    proxy_set_header   X-Real-IP  $proxy_protocol_addr;
    proxy_set_header   X-Forwarded-Proto  $scheme;
    proxy_set_header   X-Forwarded-For    $proxy_add_x_forwarded_for;
    proxy_set_header   X-HubSpot-Client-IP $proxy_protocol_addr;
  }

proxy_ssl_name www.example.com;
proxy_ssl_server_name on;

​

Set up a reverse proxy with Cloudflare (Orange-to-Orange)

​

1. Configure the CNAME record in Cloudflare

1. Log in to your Cloudflare account.
2. Navigate to the zone for your domain.
3. Navigate to DNS > Records.
4. Click Add record.
5. Set the record type to CNAME.
6. In the Name field, enter the subdomain you added to HubSpot in the previous step above.
7. In the Target field, enter your HubSpot proxy domain (e.g., 123456.sites-proxy.hscoscdn00.net).
8. Ensure the Proxy status is set to Proxied (orange cloud). This is critical, as the record must be orange-clouded for the O2O configuration to work.
9. Click Save.

​

2. Configure request header transform rules

1. In your Cloudflare dashboard, navigate to the zone for your domain.
2. Go to Rules → Transform Rules (or Rules → Overview, then click Modify Request Header).
3. Click Create rule.
4. Give the rule a descriptive name (e.g., HubSpot Reverse Proxy Headers).
5. Under When incoming requests match, set the condition to:
   • Field: Hostname
   • Operator: equals
   • Value: Your domain name (e.g., www.example.com)
6. Under Then, add the following header modifications:
   • Set X-HS-Public-Host:
   • Action: Set static
   • Header name: X-HS-Public-Host
   • Value: Your destination domain (e.g., www.example.com)
   • Set X-HubSpot-Trust-Forwarded-For:
     • Action: Set static
     • Header name: X-HubSpot-Trust-Forwarded-For
     • Value: true
7. Review the rule configuration, then click Deploy.

​

3. Path-based proxying with DNS override (optional)

1. In your Cloudflare dashboard, navigate to the zone for your domain.
2. Navigate to Rules > Origin Rules.
3. Click Create rule.
4. Give the rule a descriptive name (e.g., HubSpot /blog proxy).
5. Under When incoming requests match, set the condition to:
   • Field: URI Path
   • Operator: starts with
   • Value: /blog (or whatever path(s) you want to proxy to HubSpot)
6. Under Then, enable DNS override and set the destination to your HubSpot subdomain (e.g., hub.example.com).
7. You may also need to set a host header override to ensure the correct Host header is sent to HubSpot. Set it to your HubSpot subdomain (e.g., hub.example.com).
8. Review the rule configuration, then click Deploy.

1. A visitor requests https://www.example.com/blog.
2. Cloudflare matches the origin rule for the /blog path.
3. The DNS override sends the request to hub.example.com (which is orange-clouded to HubSpot’s zone).
4. HubSpot receives the request and serves the content.
5. For all other paths (e.g., https://www.example.com/about), the request goes to your existing hosting provider as normal.

​

4. Confirm the configuration is correct

1. In your HubSpot account, go to Settings → Website → Domains & URLs.
2. Next to your domain, click the Edit dropdown and select Verify Reverse Proxy Connection.
3. Click any category labeled Failed to view recommendations for fixing the issue.
4. After implementing fixes, click Refresh test to re-check.

https://[your-full-domain]/_hcms/diagnostics

• The current time value changes on every load (confirms the page is not cached).
• The User-Agent is consistent with your browser.
• The Accept-Language value is consistent with your browser.
• The Accept-Encoding header is * (ensures responses are compressed).
• 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 whatismyip.com).
• The IP-Determined Location values are accurate to your location.

https://[your-full-domain]/_hcms/_worker/headers

• X-Forwarded-For
• X-HubSpot-Trust-Forwarded-For (should be true)
• X-HS-Public-Host (should match your domain)

​

Troubleshooting

• Verify that your transform rule is deployed and not in draft state.
• Confirm the Hostname equals condition matches your domain exactly (including subdomain).
• Check that you are not overwriting headers with another transform rule that runs later. Cloudflare applies rules in the order they are listed; rules further down the list can override earlier ones.
• Use the headers endpoint to inspect exactly what HubSpot is receiving.

• Ensure your Cloudflare configuration does not cache responses for paths originating from HubSpot. HubSpot automatically manages content caching on its CDN. If Cloudflare caches responses, pages may not update for hours or days.
• Check that no Cloudflare Page Rules or Cache Rules are set to cache everything for your domain.