Short answer: make custom-domain onboarding a sequence of five evidence checks: the right tenant claimed the hostname, the edge configuration exists, DNS points where expected, HTTPS is ready, and a real request reaches the right application. These are application UI states, not names of a particular provider's API statuses. Keeping them separate gives customers a useful next action instead of a generic “pending” badge. We built our DNS onboarding, monitoring, and webhooks to help you ship that clarity inside your own product.
Five checks your product can explain
| Evidence | Useful UI copy | Who acts next? |
|---|---|---|
| Claim recorded | “We saved this domain for your workspace.” | Your app verifies permission and prevents a second tenant from claiming it. |
| Proxy configured | “Your domain is ready for DNS setup.” | Your backend stores the provider's domain or virtual-host ID. |
| DNS observed | “DNS points to the right place.” | The customer fixes records if the observed answer differs. |
| Certificate ready | “Your domain is secured with HTTPS.” | Your backend confirms the certificate is active, then tests the application route. |
| Application verified | “Your domain is live.” | Your backend proves the right tenant answers over HTTPS. |
While certificate validation is pending, show “We're securing your domain” and offer a retry or support path if it stalls. A saved configuration isn't a green light to send customers to the new URL. DNS caches and certificate validation can make later checks lag behind. If an HTTPS test fails, keep the prior evidence visible so a support engineer can identify which layer changed.
Start with an ownership rule, not an API call
Normalize the hostname, reject invalid or conflicting claims, and attach it to one tenant in your database. Decide how your team resolves a domain already used by another customer. A DNS answer pointing at your edge doesn't, by itself, tell you which account should own the name. Treat transfer and deletion as explicit product actions with an audit trail.
Only then create the edge configuration. Our Virtual Hosts API connects an incoming address to a target address. You can automate the mapping or manage it in our dashboard while keeping the tenant association in your app.
Make the DNS step precise
Show the exact record type, name, and value; include a copy action and a “check again” control. An apex may need an A record or a provider-specific alias rather than a CNAME. The apex guide explains those branches. Our widget and headless mode put provider-specific instructions inside your UI, so you can give customers useful help without maintaining every DNS provider flow yourself. Keep the later checks visible until the domain is live.
Tell customers which record was observed when a check fails. “We found an old A record” gives them a task; “verification failed” doesn't. If their DNS is proxied through another service, verify the public route they actually created.
Use status signals, then verify the user outcome
Provider status polling and webhooks are useful ways to update the UI. We provide monitor-update webhooks for domain status observations and a separate creation event. A creation event isn't an SSL-ready event. Process repeated webhook deliveries safely and reconcile against the current API state.
The final check should request https://customer.example using the customer's hostname, validate the certificate, and confirm that the expected tenant rendered. A healthy provider status can't prove your app's login, redirects, cookies, or content routing. Run at least one representative authenticated flow before marking the first production domain live.
Make the live domain ready for real customer traffic
Once the domain connects, protect the forms and traffic your customer will actually use. Our WAF and DDoS protection is built into the dedicated cluster serving your SaaS domains, with a response informed by your traffic and shared threat intelligence.
For contact, signup, or other browser forms, add Edge Verify. Its script is served from the customer's own domain and the edge checks form submissions. Start in monitor mode so you can inspect outcomes without blocking, then move to enforce once your legitimate form flow is passing. Your app continues to own login and tenant authorization.
Keep the connection visible after launch
DNS may later move away, an origin may stop answering, or a tenant may disconnect the domain. Keep the last successful check and current observation separate, and give support a way to see both. On removal, stop serving the old tenant, remove the edge mapping at the right time, and tell the customer to remove the DNS record. The security guide covers the ownership and dangling-record risks behind that sequence.
For the full infrastructure path behind these screens, start with the production guide. Our API documentation gives you the virtual-host, DNS-check, and webhook contracts. Our engineers can help with integration and production issues. You can start on our managed cloud with published pricing and keep a self-hosted path available as your requirements grow.
Frequently asked questions
When should my SaaS show that a custom domain is connected?
Show connected only after the authorized tenant claim is recorded, the edge is configured, DNS points correctly, a valid certificate is active, and a real HTTPS request reaches the intended tenant. Keep saved, DNS, and certificate progress separate. Our monitoring and webhooks provide edge observations, while your application verifies the final customer experience.
How long does a customer DNS change take to become visible?
There is no single reliable time for every DNS change. The provider must publish the record, and recursive resolvers can retain the previous answer until its cache expires. Check the authoritative answer and public resolvers, show the record actually observed, and offer a check-again action. Treat certificate readiness as a separate step after DNS rather than promising an immediate connection.
Can customers follow DNS setup inside my SaaS product?
Yes. Our DNS widget presents provider-specific instructions and verifies requested records inside your product. Headless mode lets your own UI use those instructions and checks. The customer still makes the required change at their DNS provider; your application controls who may claim the hostname and confirms the final HTTPS route to the tenant.
Should I use polling or webhooks for custom domain status?
Webhooks let your application react to domain observations, while API reads let it reconcile the current state. We provide creation and monitor-update events with distinct meanings: creation doesn't mean HTTPS is ready. Authenticate deliveries, process repeats idempotently, and reconcile current API status so retries or delayed events don't move the onboarding UI backward.
Why can DNS be verified while a custom domain SSL certificate is still pending?
DNS and certificate issuance are different checks. The record may point correctly while domain validation, certificate issuance, or the actual HTTPS route is still pending. Show that DNS is correct and that the domain is being secured, then confirm a valid certificate and tenant response. A proxy in front of the edge can also change the validation path, so test the public route.