Tracking domain
Send the web SDK's requests through a subdomain of your own site.
A tracking domain is a subdomain of your site, such as t.example.com, that Voidhash serves for
your project, so the web SDK's requests go to your own domain instead of api.voidhash.com. Ad
blockers and tracking prevention block such requests far less often. Unlike a
first-party proxy you run yourself, it keeps each visitor's own IP
address and location.
Tracking domains are available on Voidhash Cloud only.
Before you start
- You can add DNS records for the domain, for example
example.com. - You have permission to edit the project's settings. Without it, you can see tracking domains but not add, check or remove them.
Set up the domain
Add the domain
In Studio, open Settings → General and find the Tracking domain card. Enter the hostname,
for example t.example.com, and select Add domain. You can also use voidhash domain add in the
CLI.
The hostname must be a subdomain, as DNS does not allow a CNAME at the root of a domain. Pick a
neutral name: blocklists match names such as analytics or tracking.
Create the DNS record
Studio shows the records for the domain. At your DNS provider, create the CNAME record:
| Type | Name | Value |
|---|---|---|
CNAME | t.example.com | <target>.track.voidhash.link |
Copy the full value from Studio: <target> is unique to your project, and pointing at it proves
the domain is yours.
If your DNS provider flattens CNAME records or hides them behind its own proxy, Studio also asks
for a TXT record named _voidhash-verify.t.example.com. Add it and keep the CNAME. TXT records
marked optional only speed up the certificate.
Wait for the domain to become active
Voidhash checks the domain every few minutes in its first hour, then less often. Select Check now once your record is in place. The domain moves from Waiting for DNS to Issuing certificate, usually for a few minutes, then to Active.
Point the SDK at the domain
Once the domain is Active, set it as baseUrl:
import { createVoidhashClient } from "@voidhash/web";
export const voidhash = createVoidhashClient({
baseUrl: "https://t.example.com",
publishableKey: "vh_pk_...",
});Check it in the browser
In the browser's developer tools, open the Network tab. Requests to t.example.com/i/v1/...
and t.example.com/api/v1/sdk/... succeed, and none go to api.voidhash.com.
Returning visitors are unaffected by the move: the SDK stores its state per project, not per
baseUrl.
Statuses
| Status | Meaning | What to do |
|---|---|---|
| Waiting for DNS | Voidhash cannot see the CNAME record to your project's target yet. | Check the record's name and value at your DNS provider. DNS changes can take a while to spread; select Check now later. |
| Issuing certificate | The record is in place and a certificate is being made. | Wait a few minutes. The optional TXT records can speed this up. |
| Active | The domain is serving your project. | Keep the CNAME record in place. |
| Failed | Studio shows the reason. | If the record was removed or changed, restore it and select Check now. If the certificate could not be issued, check the record, then remove the domain and add it again. |
Active domains are checked daily and must keep proving they are yours:
- If the
CNAMEpoints somewhere else, the domain becomes Failed and stops serving. Point the record back and select Check now. - If the
CNAMEcan no longer be seen, for example behind your DNS provider's proxy, the domain keeps working and Studio asks for theTXTrecord. Without it, the domain is turned off after 7 days.
A domain whose records are not in place within 7 days of adding it is removed.
Several projects can add the same hostname; the one whose DNS proves it gets it. If the DNS later proves another project, for example when a domain moves from an agency's project to yours, the hostname moves and the previous project is told why.
Security
A tracking domain accepts only the publishable key of its own project; other keys get 401.
Secret keys and CLI keys are rejected too, so send server-side events to https://api.voidhash.com.
Only the SDK's endpoints are served; any other path answers 404.
Adding and removing tracking domains is recorded in the audit log, which you read through the API, CLI or MCP server.
Limits
A project can have up to 5 tracking domains, for example one per website. Each hostname serves only one project.
Remove a domain
First point baseUrl back at the default address, or another active tracking domain, and deploy
that change. Then remove the domain in Studio. Requests through a removed domain stop working
shortly after, and events sent through it are lost. Delete the CNAME record afterwards.
Self-hosted Voidhash
Self-hosted installs do not offer tracking domains; your API already runs on a domain you control. To serve it from your website's domain, use a first-party proxy.
Next steps
Something wrong or missing on this page? Tell us by email or on Discord.