Custom Domain Configuration for Career Pages
Recruiters want careers.theirdomain.com. Getting them there without turning DNS and SSL into a support nightmare.
Overview
I implemented the custom domain feature for a recruitment product’s career and job pages. Recruiters could point a subdomain (e.g. careers.theirdomain.com) at our platform; we guided them through adding a CNAME or TXT record, verified ownership, and triggered SSL provisioning through our hosting provider. The backend stored domain config, verification status, and certificate state so the frontend could show clear next steps when something was pending or failed.
Tech Stack
Impact & Scale
- Recruiters can use their own domain for career pages (e.g. careers.company.com)
- DNS verification and SSL provisioning handled without manual steps
- Single flow in the product for adding and verifying a custom domain
Key Challenges & Solutions
Verifying ownership without blocking the flow
We needed to confirm the recruiter controlled the domain before enabling it. We used a TXT record with a unique token and a background job that periodically checked DNS. The UI showed "pending verification" and updated when the check passed, so users did not have to refresh or re-submit.
Explaining DNS to non-technical users
Copy-pasting a CNAME or TXT record is error-prone. We provided exact values, step-by-step instructions, and links to common DNS providers’ docs. Where possible we detected the DNS host and tailored the instructions to reduce support load.
Handling SSL lifecycle
Certificate issuance and renewal were delegated to our host. We stored the domain and left the host to manage certs; our job was to show "active" or "provisioning" or "failed" and to surface any error message from the provider so users could fix misconfigurations.
Technical Highlights
- Domain model with verification status, DNS records to add, and SSL state
- Background job for DNS verification with configurable retry and backoff
- Integration with hosting provider APIs for adding a custom domain and checking certificate status
- Settings UI with instructions, current status, and inline error messages
Role and scope
I owned the backend and settings UI for custom domains. That included the API for adding and removing domains, the verification job, and the integration with the hosting and SSL provider. I worked with the team that owned the routing layer so that verified domains correctly resolved to the right tenant’s pages.
Architecture
Domain records are stored per tenant. When a recruiter adds a domain, we generate a verification token and return the exact DNS record to add. A scheduled job queries DNS; on success we mark the domain verified and call the host to attach the domain and start SSL. The frontend reads domain and verification state from the API and renders the right copy and status.
Lessons learned
- DNS is eventually consistent. Polling with backoff and clear "pending" states in the UI set the right expectations and avoided "it says verified but it doesn’t work" confusion.
- Provider errors need to be human-readable. When SSL or domain attach failed, we stored and displayed the provider’s message so power users could fix DNS or contact their host without going through support.
- One source of truth for status. Keeping verification and SSL state in our database (and syncing from the provider when needed) made the UI predictable and made debugging easier than relying only on provider dashboards.
Interested in discussing this project or working together? Get in touch.