Forcing a Subdomain in Entri Sell (domain.purchased webhook)

Overview

Some integrations want every domain purchased through their Entri Sell flow to use a specific subdomain, for example galleries.newdomain.com instead of the bare root domain. This article explains how the subdomain field in Entri webhooks is actually determined during a Sell flow, and how to configure your integration so a fixed subdomain is applied consistently and reported correctly.

How the subdomain webhook field works

The subdomain field you see in domain.purchased and domain.added webhook events is not automatically derived from whatever host value you set in your dnsRecords. It's tied to a placeholder mechanism, the {SUBDOMAIN} dynamic configuration variable, that Entri Sell shares with Entri Connect.

This means that if you set a custom host like "galleries" directly in your dnsRecords without using the {SUBDOMAIN} placeholder, the DNS record is still created correctly on the domain, but the subdomain webhook field may report something else entirely.

Important: This is expected behavior, not a bug. The DNS records you send and the subdomain webhook field are two independent things unless you explicitly connect them using the {SUBDOMAIN} placeholder.

Forcing a fixed subdomain

To have every domain purchased through your Sell flow use the same subdomain, and have that subdomain correctly reflected in your webhooks, combine the following in your purchaseDomain() config:

1. forceSubDomain: true

2. defaultSubdomain: "galleries" (replace with your desired subdomain)

3. The {SUBDOMAIN} placeholder as the host value in your dnsRecords, rather than hardcoding the subdomain directly

entri.purchaseDomain({
  applicationId: "your-app-id",
  token: yourToken,
  forceSubDomain: true,
  defaultSubdomain: "galleries",
  dnsRecords: [
    {
      type: "CNAME",
      host: "{SUBDOMAIN}",
      value: "yourapp.example.com",
      ttl: 300
    }
  ]
});

With this configuration:

• Every domain purchased through the flow will have galleries configured as its subdomain (e.g. galleries.newdomain.com)

• The subdomain field in the domain.purchased and domain.added webhook events will correctly report "galleries"

Alternative: hardcoding the subdomain directly

If you don't rely on the webhook payload to know which subdomain was configured, you can skip the placeholder and hardcode the value directly as the host:

dnsRecords: [
  {
    type: "CNAME",
    host: "galleries",
    value: "yourapp.example.com",
    ttl: 300
  }
]

This still creates the correct galleries.newdomain.com record. However, the subdomain field in your webhook won't necessarily reflect "galleries", since it isn't derived from raw host values (see the table above). We recommend the forceSubDomain + defaultSubdomain approach if your integration reads the subdomain field from webhooks.

Common mistake: expecting the webhook to mirror dnsRecords.host

What happens:

1. You configure a CNAME with a custom host (e.g. "galleries") in dnsRecords, without using the {SUBDOMAIN} placeholder.

2. The DNS record is created correctly on the domain.

3. The subdomain field in the webhook reports something else, like "www" or null, instead of "galleries".

The fix: Use the {SUBDOMAIN} placeholder together with forceSubDomain and defaultSubdomain whenever you need the webhook to report a specific subdomain. Don't rely on the raw host value in dnsRecords for this.

Related parameters

FAQ

Does this apply to Entri Connect too? Yes. The {SUBDOMAIN} placeholder, defaultSubdomain, and forceSubDomain mechanics are shared between Connect and Sell.

Is the mismatch between my DNS records and the webhook's subdomain field a bug? No. It's expected behavior based on how the subdomain key was originally designed. Use the configuration above if you need the webhook to reflect a specific subdomain.

Need additional help? Contact our support team through the Entri dashboard or visit our help center for more resources.