Custom Domain Kit
Docs/Quickstart

First Test Domain

First Test Domain

Use this checklist to test the full setup flow with a real hostname.

1. Open the Embedded Setup UI

Open the page in your SaaS app where you embedded <custom-domainkit-setup>.

Confirm that:

  • The page loads a setup session from your server.
  • The setup UI renders without exposing the app secret.
  • The setup UI is scoped to the expected tenantId.

2. Add a Hostname

Click + Add Domain and enter a hostname you control, such as:

docs.customer-example.com

The setup UI should show DNS records after the domain is created.

3. Add DNS Records

Add the CNAME and any TXT records shown in the setup UI.

Common mistakes:

  • Adding the zone name twice.
  • Pasting a TXT value with missing characters.
  • Enabling DNS proxying before validation is complete.
  • Adding records to the wrong DNS zone.

4. Refresh Status

Click Check status after DNS has propagated.

The domain is ready for traffic testing when the setup UI shows the domain as active and no CNAME target warning remains.

5. Test Traffic

Open the hostname in a browser:

https://docs.customer-example.com

Your app should resolve the tenant by X-CDK-Original-Host, X-Forwarded-Host, or Host.

6. Check Webhooks

Confirm that your webhook receiver processed the domain.status_changed event and updated your local domain row.