Hostnames — Custom Domain Management & DNS Verification

Every multi-tenant platform eventually needs to let customers use their own domain — app.theircustomer.com instead of yourplatform.com/theircustomer. Done by hand, this means writing DNS polling loops, managing retry state, wiring up SSL provider webhooks, and threading custom-domain logic through every service that cares about routing. Granit.Hostnames solves this once, generically.

It binds a custom domain to any opaque resource (OwnerType + OwnerId) and owns the full lifecycle: DNS TXT-record verification with exponential backoff, SSL certificate provisioning via webhook callback, and notification to consumers via ETOs — no reverse dependency on your application, no schema changes in your modules.

Why custom domains?

Challenge	DIY	Granit.Hostnames
DNS ownership proof	Custom polling loop, bespoke retry logic	`HostnameVerificationJob` every 5 min, exponential backoff built-in
SSL provisioning	Direct CDN/Let’s Encrypt integration per service	Webhook endpoint (`/certificate-status`) updates `CertificateStatus` in one place
Resource binding	Custom join tables in each consumer	Generic `OwnerType + OwnerId` — zero schema changes in consumers
Cross-service events	Direct calls or shared DTOs between modules	`HostnameVerifiedEto`, `HostnameCertificateSecuredEto` — consumers react without coupling
User communication	Notify users yourself	2 notification types, 36 templates, 18 cultures, shipped

Website builder scenario

The canonical use case is a website builder or white-label portal where each customer gets their own branded domain:

Customer registers app.theircustomer.com in your portal UI → POST /api/v1/hostnames
Your UI shows the DNS TXT record to add — the customer updates their registrar
HostnameVerificationJob polls every 5 min; on success it publishes HostnameVerifiedEto
Your website module handles the ETO and activates the domain in its own routing table — no import of Granit.Hostnames required
The SSL provider calls /certificate-status → HostnameCertificateSecuredEto
If DNS isn’t configured after N attempts, HostnameVerificationFailedNotificationType notifies the customer automatically

The same pattern applies to billing portals, API gateways, and any multi-tenant surface that needs per-tenant vanity domains.

Package structure

DirectoryGranit.Hostnames/ Domain model, ManagedHostname aggregate, DNS state machine, backoff
- Granit.Hostnames.EntityFrameworkCore HostnamesDbContext, EfManagedHostnameStore, EfHostnameResolver
- Granit.Hostnames.Endpoints CRUD, availability check, /verify-now, /certificate-status webhook
- Granit.Hostnames.BackgroundJobs HostnameVerificationJob (every 5 min), batch service
- Granit.Hostnames.Notifications hostname_verified + hostname_verification_failed (36 templates × 18 cultures)

Package	Role	Depends on
`Granit.Hostnames`	`ManagedHostname` aggregate, `IHostnameResolver`, `IHostnameVerifier`, `IManagedHostnameWriter`/`Reader`, DNS FSM, exponential backoff	`Granit`
`Granit.Hostnames.EntityFrameworkCore`	`HostnamesDbContext`, `EfManagedHostnameStore`, `EfHostnameResolver`, `HostnamesOptions`	`Granit.Hostnames`, `Granit.Persistence`
`Granit.Hostnames.Endpoints`	Minimal API: CRUD, availability check, `/verify-now`, `/certificate-status` webhook	`Granit.Hostnames`, `Granit.Authorization`
`Granit.Hostnames.BackgroundJobs`	`HostnameVerificationJob` (5-min cron), `HostnameVerificationBatchService`	`Granit.Hostnames`, `Granit.BackgroundJobs`
`Granit.Hostnames.Notifications`	`HostnameVerifiedNotificationType`, `HostnameVerificationFailedNotificationType`	`Granit.Hostnames`, `Granit.Notifications`

Dependency graph

graph TD
    HN[Granit.Hostnames] --> CO[Granit]
    EF[Granit.Hostnames.EntityFrameworkCore] --> HN
    EF --> P[Granit.Persistence]
    EP[Granit.Hostnames.Endpoints] --> HN
    EP --> A[Granit.Authorization]
    BJ[Granit.Hostnames.BackgroundJobs] --> HN
    BJ --> BGJ[Granit.BackgroundJobs]
    NT[Granit.Hostnames.Notifications] --> HN
    NT --> N[Granit.Notifications]

Hostname lifecycle

ManagedHostname drives two independent state machines: DNS verification and certificate provisioning. Both advance independently — a hostname can be DNS-verified while certificate provisioning is still in progress.

DNS verification

stateDiagram-v2
    [*] --> Pending : Register
    Pending --> Verifying : BeginVerification
    Verifying --> Active : DNS check passes
    Verifying --> Error : Check fails (max attempts)
    Error --> Verifying : Retry (exponential backoff)
    Active --> Verifying : ReVerify (ownership refresh)

State	Description
`Pending`	Hostname registered; TXT record not yet checked
`Verifying`	Background job polling DNS; backoff counter incrementing
`Active`	TXT record found and validated; hostname is live
`Error`	Max verification attempts reached; manual retry required

Retries use exponential backoff — delay doubles on each failed attempt up to a configurable ceiling (HostnamesOptions.MaxBackoffMinutes).

Certificate status

stateDiagram-v2
    [*] --> Unprovisioned
    Unprovisioned --> Provisioning : DNS Active
    Provisioning --> Secured : /certificate-status webhook (success)
    Provisioning --> Error : /certificate-status webhook (failure)
    Error --> Provisioning : Re-provision

Status	Description
`Unprovisioned`	DNS not yet active; SSL provider not contacted
`Provisioning`	SSL provider notified; awaiting certificate issuance
`Secured`	Certificate issued and installed
`Error`	Provisioning failed; webhook reported an error

The /certificate-status webhook is a host-level endpoint — the SSL provider calls it to report provisioning outcomes. It requires the Hostnames.Certificates.Report permission, scoped to host-level callers.

[DependsOn(
    typeof(GranitHostnamesEntityFrameworkCoreModule),
    typeof(GranitHostnamesEndpointsModule),
    typeof(GranitHostnamesBackgroundJobsModule),
    typeof(GranitHostnamesNotificationsModule))]
public class AppModule : GranitModule { }

builder.AddGranitHostnames();
builder.AddGranitHostnamesEntityFrameworkCore(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Hostnames")));

{
  "Hostnames": {
    "IngressTarget": "customers.platform.example.com",
    "TxtChallengePrefix": "_granit-challenge",
    "VerificationBatchSize": 100,
    "VerificationConcurrency": 10,
    "DnsQueryTimeoutSeconds": 5,
    "CertificateWebhookSecret": "vault:secret/data/hostnames#webhook-secret",
    "CertificateWebhookSignatureHeader": "X-Webhook-Signature-256"
  }
}

Use this when another service owns the HTTP surface and your application only needs to resolve or verify hostnames programmatically.

[DependsOn(
    typeof(GranitHostnamesEntityFrameworkCoreModule),
    typeof(GranitHostnamesBackgroundJobsModule))]
public class AppModule : GranitModule { }

builder.AddGranitHostnames();
builder.AddGranitHostnamesEntityFrameworkCore(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Hostnames")));

Core abstractions

IHostnameResolver

Resolves a ManagedHostname by its hostname string or by owner identity:

public interface IHostnameResolver
{
    Task<ManagedHostname?> FindByHostnameAsync(
        string hostname,
        CancellationToken cancellationToken = default);

    Task<IReadOnlyList<ManagedHostname>> FindByOwnerAsync(
        string ownerType,
        Guid ownerId,
        CancellationToken cancellationToken = default);
}

IManagedHostnameWriter / IManagedHostnameReader

CQRS split — inject the interface that matches your intent:

// Read-side: querying hostname metadata
public class HostnameQueryHandler(IManagedHostnameReader reader) { }

// Write-side: registering or updating hostnames
public class HostnameCommandHandler(IManagedHostnameWriter writer) { }

IHostnameVerifier

The DNS verification abstraction. Inject it to trigger on-demand verification outside the background job:

public interface IHostnameVerifier
{
    Task<VerificationResult> VerifyAsync(
        ManagedHostname hostname,
        CancellationToken cancellationToken = default);
}

VerificationResult carries the resolved DNS values and the failure reason when the check does not pass, allowing callers to surface actionable feedback to users.

Registering a hostname

public class RegisterHostnameHandler(IManagedHostnameWriter writer)
{
    public async Task HandleAsync(RegisterHostnameCommand cmd, CancellationToken ct)
    {
        var hostname = ManagedHostname.Create(
            id:        Guid.NewGuid(),
            hostname:  cmd.Hostname,          // e.g. "app.customer.com"
            ownerType: "CmsPortal",
            ownerId:   cmd.PortalId);

        await writer.AddAsync(hostname, ct).ConfigureAwait(false);
    }
}

The aggregate is created in Pending state. The background job picks it up within the next poll interval and begins DNS verification.

Endpoints

All routes live under the Hostnames OpenAPI tag.

Method	Route	Permission	Description
`GET`	`/api/{version}/hostnames`	`Hostnames.Hostnames.Read`	List managed hostnames (filterable by `ownerType`, `ownerId`, `verificationStatus`)
`POST`	`/api/{version}/hostnames`	`Hostnames.Hostnames.Manage`	Register a new custom hostname
`GET`	`/api/{version}/hostnames/{id}`	`Hostnames.Hostnames.Read`	Get hostname details and current status
`DELETE`	`/api/{version}/hostnames/{id}`	`Hostnames.Hostnames.Manage`	Remove a managed hostname
`GET`	`/api/{version}/hostnames/availability`	— (public)	Check whether a hostname is already registered
`POST`	`/api/{version}/hostnames/{id}/verify-now`	`Hostnames.Hostnames.Manage`	Trigger an immediate DNS check (bypasses backoff)
`POST`	`/api/{version}/hostnames/certificate-status`	`Hostnames.Certificates.Report`	SSL provider webhook — updates `CertificateStatus`

Availability check

GET /api/{version}/hostnames/availability?hostname=app.customer.com returns { "available": true }. This endpoint is unauthenticated so that registration UIs can validate before prompting the user to configure DNS.

Certificate-status webhook

The /certificate-status endpoint is designed to be called by the SSL provider (e.g., Cloudflare for SaaS, a Let’s Encrypt proxy). It accepts a JSON body describing the outcome and transitions CertificateStatus accordingly, then publishes HostnameCertificateSecuredEto or HostnameCertificateFailedEto.

Background jobs

Job	Cron	Description
`HostnameVerificationJob`	`/5 * * *`	Fetches all hostnames in `Pending`/`Verifying`/`Error` state and dispatches them to `HostnameVerificationBatchService` for DNS checking

HostnameVerificationBatchService processes the batch in parallel, applies exponential backoff between retries, and transitions each hostname to Active or Error depending on the DNS check outcome.

Notifications

Granit.Hostnames.Notifications ships 2 notification types with 36 templates (2 × 18 cultures):

Type	Name	Severity	Opt-out
`HostnameVerifiedNotificationType`	`hostnames.hostname_verified`	Info	Yes
`HostnameVerificationFailedNotificationType`	`hostnames.hostname_verification_failed`	Warning	No

Default channel: InApp + Email. Each notification carries the hostname string and owner identity so the consumer can route the message to the right user.

Events

ManagedHostname publishes ETOs on verification and certificate transitions. Consume them via Wolverine handlers to react in downstream services without coupling to Granit.Hostnames.

ETO	Trigger	Key fields
`HostnameVerifiedEto`	DNS check passes → `Active`	`HostnameId`, `Hostname`, `OwnerType`, `OwnerId`, `VerifiedAt`
`HostnameVerificationFailedEto`	Max attempts reached → `Error`	`HostnameId`, `Hostname`, `OwnerType`, `OwnerId`, `FailureReason`, `AttemptCount`
`HostnameCertificateSecuredEto`	Webhook reports success → `Secured`	`HostnameId`, `Hostname`, `CertificateExpiresAt`
`HostnameCertificateFailedEto`	Webhook reports failure → certificate `Error`	`HostnameId`, `Hostname`, `FailureReason`

public class HostnameVerifiedHandler(ILogger<HostnameVerifiedHandler> logger)
{
    public Task HandleAsync(HostnameVerifiedEto eto, CancellationToken ct)
    {
        logger.LogInformation(
            "Hostname {Hostname} verified for {OwnerType}/{OwnerId}",
            eto.Hostname, eto.OwnerType, eto.OwnerId);
        return Task.CompletedTask;
    }
}

Permissions

Permission	Scope	Description
`Hostnames.Hostnames.Read`	Standard	List and read managed hostnames
`Hostnames.Hostnames.Manage`	Standard	Register, delete, and trigger verification
`Hostnames.Certificates.Report`	Host-level	Allowed for SSL provider webhook callers only

Hostnames.Certificates.Report is a host-level permission — it is not assignable to regular users. Grant it to the machine account or API key used by your SSL provider to call the /certificate-status webhook.

Configuration reference

Property	Default	Description
`IngressTarget`	`null`	Platform CNAME target customers point their hostname at. When set, `BeginVerification` runs on creation so the response already carries the DNS records.
`TxtChallengePrefix`	`"_granit-challenge"`	DNS label prefix for the TXT ownership challenge — the full name is `{prefix}.{host}`.
`VerificationBatchSize`	`100`	Hostnames fetched by the poller per tick.
`VerificationConcurrency`	`10`	Parallel DNS verifications per tick, so one slow delegation chain cannot block the batch.
`DnsQueryTimeoutSeconds`	`5`	Per-query DNS timeout.
`CertificateWebhookSecret`	`null`	Shared secret for the HMAC-SHA-256 signature on `POST /{id}/certificate-status`. Skipped when null (local dev only) — source it from Vault.
`CertificateWebhookSignatureHeader`	`"X-Webhook-Signature-256"`	Header carrying the signature; override to match your edge provider.

Public API summary

Category	Key types	Package
Module	`GranitHostnamesModule`, `GranitHostnamesEntityFrameworkCoreModule`, `GranitHostnamesEndpointsModule`, `GranitHostnamesBackgroundJobsModule`, `GranitHostnamesNotificationsModule`	—
Aggregate	`ManagedHostname`, `VerificationStatus`, `CertificateStatus`	`Granit.Hostnames`
Interfaces	`IHostnameResolver`, `IHostnameVerifier`, `IManagedHostnameWriter`, `IManagedHostnameReader`	`Granit.Hostnames`
Value objects	`VerificationResult`, `HostnamesOptions`	`Granit.Hostnames`
ETOs	`HostnameVerifiedEto`, `HostnameVerificationFailedEto`, `HostnameCertificateSecuredEto`, `HostnameCertificateFailedEto`	`Granit.Hostnames`
Persistence	`HostnamesDbContext`, `EfManagedHostnameStore`, `EfHostnameResolver`	`Granit.Hostnames.EntityFrameworkCore`
Background	`HostnameVerificationJob`, `HostnameVerificationBatchService`	`Granit.Hostnames.BackgroundJobs`
Notifications	`HostnameVerifiedNotificationType`, `HostnameVerificationFailedNotificationType`	`Granit.Hostnames.Notifications`
Extensions	`AddGranitHostnames()`, `AddGranitHostnamesEntityFrameworkCore()`	—