FAQ

Why is my domain still pending?

Check that the customer added every required DNS record, used the right DNS zone, and did not accidentally duplicate the zone name. Then click Check status again after DNS propagation.

Why does an active domain still not open?

Confirm the CNAME target is ready and that your origin URL is reachable over HTTPS. Also check that your app can route the incoming hostname to the right tenant.

When can I test traffic?

Test traffic after the domain is active and the setup UI no longer shows a CNAME target warning.

What is replacement_required?

The hostname already exists in Custom Domain Kit. The user must confirm replacement and may need to add a TXT challenge to prove control of the hostname before the new setup continues.

Why did setup token validation fail?

Common causes:

• The token expired.
• The token was signed with an old app secret.
• The token tenantId does not match the component attribute.
• The component is missing setup-token-refresh-url.

Why is my webhook not arriving?

Check that the endpoint is public HTTPS, returns 2xx, and does not reject valid signatures. Remember that pending status updates do not emit domain.status_changed; the event is sent for terminal active or failed states.

Why does webhook signature verification fail?

Use the raw request body, not parsed and re-stringified JSON. Verify timestamp + "." + raw_body with the webhook signing secret, not the app secret.

Which Host header should my app read?

Prefer X-CDK-Original-Host, then X-Forwarded-Host, then Host.

Should I enable Preserve Host?

Usually no. Enable Preserve Host only if your origin expects customer hostnames in the Host header and is ready to route and terminate those hostnames.

How should I handle payment_required?

Show an account-owner billing action, refresh billing status after checkout, then retry domain creation.

What happens in Testing Mode?

Testing Mode supports up to 3 non-BYO domains and automatically deletes Testing Mode domains after 3 days.