Add official support & documentation for running Convoy behind a reverse proxy (Nginx / NPM / Cloudflare) without auto-HTTPS issues #143
Description
Is there an existing feature request for this?
- I have searched the existing issues before opening this feature request.
Describe the feature you would like to see.
Convoy v4’s current default behavior (Caddy auto-HTTPS based on APP_URL + Laravel not trusting proxy headers by default) works well for “directly exposed to the Internet” setups, but makes it very difficult to deploy Convoy behind a reverse proxy that terminates TLS — which is one of the most common production architectures.
Most users deploy Convoy behind:
Nginx / OpenResty
Nginx Proxy Manager
Cloudflare (proxied or DNS-only)
HAProxy / Traefik
Load balancers on cloud providers
In these environments:
❌ Issues encountered today
Caddy automatically forces HTTP → HTTPS redirects when APP_URL begins with https://
Redirect loops occur:
Client → HTTPS → Proxy → HTTP → Convoy → 308 → HTTPS → Proxy → HTTP → …
Laravel generates http://… asset URLs → Mixed Content errors
No official way to toggle “Reverse Proxy Mode”
No documentation describing how to properly run Convoy behind a proxy
(even though the documentation says auto-TLS doesn’t work behind proxies)
These issues are not installation errors — they are architectural incompatibilities between Convoy’s defaults and real-world deployments.
Describe the solution you'd like.
I would love to see Convoy provide first-class support for reverse proxy deployments.
✔ Preferred solution: “Reverse Proxy Mode”
Add an environment variable or preset like:
REVERSE_PROXY_MODE=true
When enabled, Convoy would:
Disable auto-HTTPS in Caddy automatically
Listen only on HTTP (port 80) internally
(auto_https off and replacing {$APP_URL} with :80)
Trust proxy headers automatically for Laravel:
X-Forwarded-Proto
X-Forwarded-Host
X-Forwarded-For
Force Laravel to generate correct HTTPS URLs when the proxy says so
(either via TrustProxies or automatic scheme detection)
Provide example reverse-proxy configs (Nginx/TLS termination)
✔ Documentation addition
Add an official section:
Deploying Convoy behind a reverse proxy (Nginx / Nginx Proxy Manager / Cloudflare / Traefik)
Including:
Example Caddyfile for HTTP-only mode
Required headers for reverse proxying
Required Laravel proxy trust configuration
Example Nginx/NPM configs
When not to use auto-TLS
How APP_URL should be set in proxy setups
This would dramatically improve user experience and avoid confusion.
Additional context to this request.
Without reverse proxy documentation or a toggle, many users deploying Convoy behind standard production proxies encounter:
Infinite redirect loops
Mixed Content errors
Cert conflicts between Caddy and external proxy
Difficulty disabling auto-HTTPS
Confusion around how to configure APP_URL
I worked through these issues by:
Manually disabling auto-HTTPS in Caddy
Replacing {$APP_URL} with :80
Adding URL::forceScheme('https') to Laravel
Clearing caches
Ensuring proper X-Forwarded headers
Configuring Nginx Proxy Manager to forward HTTP only
These steps work, but are not documented and require modifying Convoy’s shipped Caddyfile, which will break on future updates.
Providing a built-in mode + documentation would eliminate all of these problems.