Domains And Webhooks

Domains and webhooks connect console configuration to the public sites app. Domains send customers to the right tenant. Webhooks and revalidation keep public content fresh after operator changes.

Domain Model

Sites are tenant-scoped. In production, a customer may reach the site through:

• A custom domain.
• A Sophosic shop subdomain.
• A platform fallback domain.

In local development, use path routing:

http://localhost:3008/{site-slug}
http://localhost:3008/{site-slug}/shop
http://localhost:3008/{site-slug}/bookings

Keep those routing models separate when debugging. A production custom domain proves DNS and certificate behavior, while local path routing proves tenant resolution and page behavior. Mixing the two can make a healthy local route look like a broken production-domain problem.

DNS Setup

Use Settings > Domain and Email to:

• Add domain.
• Detect provider guidance.
• Review required DNS records.
• Export BIND or CSV records for a DNS administrator.
• Verify domain status.
• Configure branded email records.

Mail records should not be proxied through providers that break email delivery.

Console Setup Preview

The Domain and Email area should show enough state for an operator to know whether the public URL is ready for customers.

If the final domain is not ready, keep launch traffic on a verified fallback host or keep the workspace protected until DNS and sender state are verified.

Public Technical Routes

The sites app exposes tenant-specific technical routes such as:

Use Discovery and domain settings when these routes do not reflect the expected workspace.

Webhook Invalidation

The public site may use webhooks to refresh cached content when console data changes.

Common webhook categories:

• Branding.
• Domains.
• Products.
• Bookings.
• Pages.
• Forms.
• Help.
• Knowledge content.
• Media.
• Settings.
• Stripe.
• Shipping.

When public content appears stale, check whether the relevant category has a webhook route, whether the request was authorized, and whether the public page uses the expected cache tag.

Webhook Route Preview

Use this map when connecting a console save to the public route that should change.

Webhook delivery should be authorized, idempotent, replay-safe, and scoped to the workspace before it changes public state.

Editor APIs

Console and sites expose editor APIs for authenticated operator actions. These APIs should be used through the console/editor fetchers and service layer, not through unauthenticated public calls.

Use editor APIs only from authenticated operator surfaces because they can change workspace configuration, content, media, and launch-critical records. If a public customer flow needs the same data, expose a customer-safe read path instead of reusing an editor route.

Public APIs

Sites exposes public or customer-facing APIs for flows such as:

• Bookings.
• Checkout.
• Orders.
• Profile.
• Forms.
• Contact.
• Help.
• Reviews.
• Search.
• Tickets.

These APIs must resolve the workspace from the tenant context and should not trust client-supplied tenant identity by itself.

Domain Troubleshooting

Start with the final customer URL, not the console preview URL. Capture the host, path, DNS provider, verification state, and the workspace slug the domain should resolve to before changing records.

Safe Change Protocol

1. Change one domain, DNS, or webhook setting at a time.
2. Verify from the final customer URL.
3. Confirm public technical routes.
4. Test the customer flow that depends on the change.
5. Keep rollback simple: restore previous DNS, disable the feature, or set the site to protected while investigating.

Domain and webhook changes can make a healthy workspace appear broken from the outside. Record the previous value, the exact DNS or route change, the expected propagation window, and the rollback owner before editing production routing. After the change, test the final host, auth callback, sitemap, social preview, and one customer action.