Whitelisted Domains¶

Whitelisted Domains is a security mechanism that controls which domains are authorized to render the Waulter consent banner. If a domain is not whitelisted, the banner will not appear — the server returns HTTP 403 and nothing happens on the page.

How it works¶

When the SDK loads on a page, it calls the Waulter server with the current page's hostname. The server checks whether that hostname is authorized:

flowchart TD
    A[SDK loads on page] --> B["Server receives hostname"]
    B --> C{"Hostname matches<br/>main webURL?"}
    C -->|Yes| D["200 OK — config returned"]
    C -->|No| E{"Hostname in<br/>whitelistedDomains?"}
    E -->|Yes| D
    E -->|No| F["403 Forbidden"]

    D --> G["Banner renders normally"]
    F --> H["Nothing happens —<br/>no banner, no events, no GCM"]

    style F fill:#c62828,color:#fff
    style H fill:#c62828,color:#fff
    style D fill:#2e7d32,color:#fff
    style G fill:#2e7d32,color:#fff

The server checks two things:

1. Does the hostname match the configuration's main website URL (webURL)?
2. Does the hostname appear in the configuration's whitelisted domains list?

If neither matches, the server returns HTTP 403 Forbidden with error: "domain_not_whitelisted". The SDK receives no configuration, and the page behaves as if Waulter was never installed.

Why this matters¶

Security protection¶

Domain whitelisting prevents:

• Configuration hijacking — someone embedding your consent configuration on their domain
• Unauthorized banner rendering — the banner appearing on domains you don't control
• Data pollution — consent events from unauthorized sources appearing in your statistics

Without whitelisting, anyone could copy your SDK script tag and Configuration ID onto their site and render your consent banner, collecting consent under your configuration.

The development challenge¶

This security mechanism creates a common friction point during development: the banner won't appear on domains you haven't whitelisted.

This affects:

How to solve it¶

Option 1: Add dev domains to your whitelist¶

The simplest solution — add your development and staging domains to the configuration's whitelisted domains list:

1. Open your configuration in the Waulter dashboard.
2. Navigate to the Domains section.
3. Add your dev/staging domains (e.g. localhost, staging.example.com, project-abc.webflow.io).
4. Save the configuration.

The banner will now render on those domains exactly as it would in production.

Option 2: Use a separate DEV configuration (recommended)¶

Create a dedicated DEV configuration with its own whitelist. This keeps your PROD configuration clean and gives you separate statistics.

1. Create a DEV configuration — see DEV & Testing Workflow
2. Whitelist your dev/staging/preview domains in the DEV configuration
3. Whitelist only production domains in the PROD configuration
4. Use the DEV Configuration ID during development, switch to PROD for go-live

Configuring whitelisted domains¶

In the Waulter dashboard:

1. Navigate to your configuration.
2. Open the Domains or Settings section.
3. Add each domain you want to authorize.
4. Save the configuration.

Domain format¶

Whitelisted domains and statistics¶

In addition to being a security gate, whitelisted domains also determine which domains appear in your Statistics dashboard. Only consent events from whitelisted domains are counted in your statistics reports.

This means:

Whitelisting and scenarios¶

When using Scenarios, each configuration referenced by a scenario rule has its own whitelist. The scenario's fallback configuration and each rule-matched configuration are checked independently against the requesting hostname.

Best practices¶

Troubleshooting¶