Skip to main content
By default, every workspace’s CDN URLs live on cdn.convertly.sh: 
https://cdn.convertly.sh/{deliveryKey}/{fileId}?w=1200&format=auto
That works out of the box — nothing to configure. But for production sites, you almost always want CDN URLs on your own hostname instead: 
https://cdn.yourdomain.com/{deliveryKey}/{fileId}?w=1200&format=auto
Same URL structure, same edge cache, your brand. Same pattern imgix, Cloudinary, and Bunny use — one CNAME, automatic SSL, done. Custom CDN domains start on Pro. Pro includes 1 hostname, Business includes 3, and Enterprise limits are set by contract. Free and Starter continue to use cdn.convertly.sh.

​
How it works

You add a CNAME record from your hostname to a Convertly edge target. Convertly’s edge sees the Host header, looks up which workspace cdn.yourdomain.com is bound to, and serves the response with valid SSL. From the browser’s perspective the URL belongs to you; behind the scenes Convertly does the rendering and caching.
No origin-shielding work, no Cloudflare account, no SSL cert to manage. Convertly’s edge handles caching, format negotiation, and cert renewal for every custom hostname you add.

​
Setup

1

Pick a hostname

A subdomain on a domain you control. cdn.yourdomain.com is the convention; images.yourdomain.com and media.yourdomain.com are common alternatives.
Don’t use the same hostname your app or marketing site already serves from. Cloudflare and most browsers refuse to cache responses on hostnames that set auth cookies — you’d kill your cache hit ratio.
2

Add the hostname in Convertly

Go to Settings → Image CDN → Custom domain, click Add hostname, and enter cdn.yourdomain.com. You’ll see:
  • The CNAME target to point your DNS at (e.g. cdn-edge.convertly.sh).
  • A verification token in the form of a _convertly-verify TXT record. This proves you own the domain before we issue an SSL certificate for it.
3

Add two DNS records at your registrar

In your DNS provider (Cloudflare, Route 53, Namecheap, Vercel, etc.) add:
TypeNameValueTTL
CNAMEcdncdn-edge.convertly.shAuto / 300
TXT_convertly-verify.cdnthe verification token from SettingsAuto / 300
If your DNS is on Cloudflare, set the proxy status on the CNAME to DNS only (grey cloud). Convertly’s edge handles caching; an extra Cloudflare proxy on top isn’t needed and complicates SSL.DNS usually propagates in 1–5 minutes. The Settings page polls for the records every 30 seconds and shows a green tick once both are visible.
4

Wait for SSL

The moment we see the TXT record, we kick off SSL provisioning (Let’s Encrypt via the ACME HTTP-01 challenge over your new CNAME). It usually finishes in under a minute.The hostname’s status badge moves through Pending DNS → Pending SSL → Active. When it’s Active, your domain is live.
5

Update your delivery URLs

Pass your custom hostname as baseUrl in the SDK or loader config. Newly rendered URLs pick up the hostname automatically:
createConvertlyCdn({
  deliveryKey: process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!,
  baseUrl: "https://cdn.yourdomain.com",
});
Or set NEXT_PUBLIC_CONVERTLY_CDN_HOST=https://cdn.yourdomain.com and read it in your loader.
- https://cdn.convertly.sh/marketing/{fileId}?w=1200&format=auto
+ https://cdn.yourdomain.com/marketing/{fileId}?w=1200&format=auto
Use a delivery alias instead of cvly_pub_… when you want a readable key segment. Existing cdn.convertly.sh URLs in already-rendered HTML keep working — both hostnames are valid simultaneously.
6

Verify

# Should return 200 + image bytes on your domain
curl -I "https://cdn.yourdomain.com/<delivery-key>/<file-id>?w=400"

# Look for these headers:
#   content-type: image/webp        (or image/avif)
#   cache-control: public, max-age=31536000, immutable
#   x-convertly-cdn: edge
#   cf-cache-status: HIT            (after the first request)
If you get a 526 or SSL warning, SSL provisioning is still in flight — wait a couple of minutes and retry. If you get a 421 Misdirected Request, the hostname isn’t yet bound to a workspace in our edge config; the Settings page status badge will say what’s missing.

​
Multiple hostnames

You can bind several hostnames to the same workspace — useful for multi-brand sites or staging vs. production. Add each one in Settings → Image CDN → Custom domain; they’re all equivalent (same delivery keys, same caches, same metering). Set whichever hostname is active in your app’s baseUrl / environment config when building CDN URLs. Switch at any time without breaking previously rendered URLs on other hostnames.

​
Rotating to a new hostname

Replacing cdn.old.com with cdn.new.com:
  1. Add cdn.new.com in the dashboard. Provision DNS + SSL as above.
  2. Once Active, point your SDK baseUrl (or env var) at cdn.new.com. New URLs use the new hostname.
  3. Leave cdn.old.com bound to the workspace for as long as old URLs are still cached downstream (we recommend at least 30 days; many teams keep it indefinitely so old marketing links don’t 404).

​
SSL renewal

Certificates are auto-renewed ~30 days before expiry, transparently. As long as the CNAME stays pointed at us, you never touch it. If you delete the CNAME or change its target, renewal will fail and the hostname’s badge will turn red after the cert expires. The Settings page will show the exact failure reason.

​
Troubleshooting

SymptomCauseFix
Status stuck on Pending DNSThe CNAME or TXT record isn’t visible from public DNS yet.dig cdn.yourdomain.com and dig TXT _convertly-verify.cdn.yourdomain.com should both resolve. If they don’t, check your DNS provider for typos.
Status stuck on Pending SSLACME challenge can’t reach the CNAME target.Confirm the CNAME points at cdn-edge.convertly.sh (not an old/wrong target) and the proxy status (if on Cloudflare) is DNS only.
421 Misdirected RequestThe hostname resolves to our edge but isn’t bound to your workspace yet.The hostname needs to be Active in Settings before traffic works.
SSL_ERROR_NO_CYPHER_OVERLAP / ERR_CERT_COMMON_NAME_INVALIDCert isn’t ready or hostname mismatch.Wait for Active status. If already Active, try a hard refresh — browsers cache cert errors aggressively.
Cache miss on every requestHostname shares cookies with your app.Use a dedicated subdomain (e.g. cdn. rather than reusing www. or the apex).

​
Next steps

Set up the image CDN

Create a delivery key, attach a source, install the SDK.

Every URL parameter

Width, height, quality, fit, gravity, format, smart crop.

Presets and signed URLs

Named transformation bundles and HMAC-signed URLs.