Docs

Heroku ACM and the WAF

Overview

Heroku ACM (Automated Certificate Management) automatically provisions and renews SSL certificates for custom domains on your Heroku app. When using the WAF, Heroku ACM continues to play an important role — you should keep it enabled.

Why You Need Both Certificates

Traffic to your site passes through two encrypted connections:

  1. Visitor → WAF: Secured by the WAF certificate (GoDaddy/Starfield), which your visitors see in their browser.
  2. WAF → Heroku App: Secured by the Heroku ACM certificate, which ensures the connection between the WAF edge network and your origin server is encrypted.

Without Heroku ACM enabled, the WAF cannot establish a secure connection to your Heroku app. This can cause failed requests, SSL handshake errors, or force the WAF to connect over plain HTTP — removing encryption on the second leg of the connection.

Keep Heroku ACM Enabled

Even though visitors see the WAF certificate (not the Heroku ACM certificate), you should keep Heroku ACM enabled for two reasons:

Routing: Heroku uses ACM certificates to properly route HTTPS traffic to your application. Disabling ACM can break the WAF-to-app connection or cause certificate mismatch errors.

Portability: If you ever need to stop using the WAF, your site will still have a valid SSL certificate. With Heroku ACM in place, moving off the WAF is a single DNS change — point your domain back to Heroku and your site continues to serve HTTPS with no downtime.

Custom Domains on Heroku

Your custom domain must be added to both the WAF and your Heroku app:

  • Heroku: Add your custom domain in your Heroku app’s Settings > Domains section. This allows Heroku ACM to issue a certificate for it.
  • WAF: Your domain is configured during WAF setup. The WAF issues its own certificate for the same domain.

Both certificates cover the same domain name but secure different parts of the connection.

Heroku ACM Renewal

Heroku ACM renews certificates automatically. No action is required from your team. The WAF does not interfere with Heroku’s renewal process.

If Heroku ACM renewal fails, check that your custom domain is still listed in your Heroku app’s domain settings. Removing and re-adding the domain in Heroku will trigger a new certificate issuance.

ACM Shows Errors in the Heroku Dashboard

When using the WAF, it is normal for Heroku’s dashboard to show ACM errors or warnings for your custom domain. This happens because your DNS points to the WAF rather than directly to Heroku, and Heroku’s ACM status check expects DNS to point to Heroku.

This does not mean your site is insecure. Traffic is still encrypted end-to-end — the WAF certificate secures the visitor-to-WAF connection, and the WAF connects to your Heroku app over HTTPS.

If you ever need to switch off the WAF and point DNS back to Heroku, ACM will immediately pick back up, issue a new certificate, and work correctly with no additional configuration.

Common Issues

WAF Returns 502 or SSL Errors

If the WAF is returning 502 errors or SSL handshake failures, check that Heroku ACM is enabled and that your custom domain is listed in Heroku’s domain settings. A missing or expired Heroku ACM certificate is a common cause.

“Certificate Mismatch” in Heroku Logs

This can happen if your custom domain was removed from Heroku but is still configured on the WAF. Re-add the domain to your Heroku app to fix this.

Disabled ACM After a Heroku Stack Upgrade

Some Heroku operations can reset ACM. After a stack upgrade or app migration, verify that ACM is still enabled in your Heroku app’s Settings > SSL Certificates section.

Need Help?

If you are having trouble with Heroku ACM or the WAF connection to your Heroku app: