Domain Validation
Before it captures an environment, deploydiff checks that your organization controls the environment's domain. You prove it by publishing a small verification file on that domain. Without it, capture batches for that environment fail before any screenshot is taken.
Publish the file before your first capture batch. That is the only required step: each capture batch validates the domain by itself when it starts. A manual check exists to test the file without launching anything, but it is never a prerequisite.
The verification file
Publish a plain text file at this path on each domain you capture:
https://your-domain.com/.well-known/deploy-diff-org-<organization id>.txt
Its content must be exactly your organization id, and nothing else.
The exact path, the id, and a button to download the file ready to upload are on the Domain validations page of your organization.
The file is the same for every domain of an organization: it names the organization, not the domain.
That makes it something you add once, to the project's repository, rather than per environment. Committed among the site's static files — the public/.well-known/ folder in most frameworks — it is deployed everywhere the site is: production, staging and every preview. A new preview environment then validates without any extra step.
Check that the file is actually reachable on those deployments. Staging and previews are often behind a login or a deployment protection: either leave /.well-known/ open, or give the environment the HTTP headers that get through (see below).
What is checked
deploydiff requests the file and accepts it when:
- the response is HTTP 200, served directly — a redirect is not followed;
- the content is your organization id (surrounding spaces and line breaks are ignored);
- the server answers within 10 seconds.
A domain is the scheme, host and port of an environment's base URL. https://myapp.com and https://staging.myapp.com are two domains, and each needs the file. In the unusual case where two environments use the same domain, they share one validation.
If the environment has custom HTTP headers — for example a secret that lets deploydiff through a login wall or a firewall — they are sent with the request, so a protected staging environment can be validated like a public one.
Only public domain names can be validated. IP addresses and local hostnames are refused.
Checking a domain
You do not have to check a domain yourself — a capture batch does it when it starts, so a new environment whose deployment already carries the file needs no action at all. Check now is there for when you want to know before launching: after publishing the file for the first time, or after fixing it. It is available:
- on the environment's overview, in the Details card;
- on the organization's Domain validations page, which lists every environment with its domain and status — including the ones not checked yet.
The result is immediate. If the domain does not validate, the reason is shown: the HTTP status received, a timeout, or a content mismatch. Fix the file and check again — a domain can be checked by hand once every 20 seconds, whoever clicks.
A manual check counts like any other. A domain that validates lets the next capture batch through at once; one that fails is marked Invalid.
| Status | Meaning |
|---|---|
| Not checked yet | The domain has never been tested |
| Valid | The file was found at the last check |
| Valid — to re-check | The file was found more than 12 hours ago; the next capture batch checks again |
| Invalid | The last check failed; capture batches fail until the file is found |
Environments sharing a domain
This is unusual — environments normally have a domain each — but it can happen. A validation belongs to the domain, but each check is sent with the HTTP headers of the environment it is run for. If two environments share a domain and only one has the header that gets through a firewall, a check from the other one fails. Within 12 hours of a successful check, such a failure is shown to you but does not invalidate the domain. After 12 hours, a failed check does.
Open demo domains
To try deploydiff without a site of your own, two domains are open to every organization:
https://emooki.frhttps://boombermangame.vercel.app— this page changes on every load, so two captures of it always show a diff. Pick it to see one in practice.
They are ours, and we authorize anyone to capture them with deploydiff. An environment whose base URL is one of them needs no verification file: its status reads Open demo domain and capture batches start directly. Enter the address exactly as written — another scheme or a subdomain is a different domain.
Keep the file in place
Validation is not a one-time step. Every capture batch — manual, scheduled or automated — starts by checking the domain. A valid result is reused for 12 hours, then the file is requested again.
If the file disappears, for example after a deployment that does not include it, the next check fails and capture batches stop for that environment, scheduled ones included. Make the file part of what you deploy.
When a capture batch fails on validation
The batch ends in Error, no page is captured, and its page says the domain could not be validated, with the reason. From there:
- Publish or fix the verification file.
- Use Check now, on the batch page itself or on the environment. This step matters here: for one minute after a failed check, a new capture batch is refused without the file being requested again. A successful manual check lifts that at once.
- Launch a new capture batch.
Who can do what
Everyone in the organization can see the Domain validations page; the environments listed are the ones each person has access to. Check now is available to whoever can launch a capture batch: organization Owners and Admins, and project Members. See Roles & Permissions.