Edge routing and custom domains

Simple terms

Edge routing sends a customer domain through Apex's Cloudflare Worker when a flow needs proxy-level control.

Routes customer domains through the Apex Worker path for edge-managed experiences and SSL-for-SaaS style storefront handling.

Routes

• /settings/developers?tab=edge
• Legacy /installation/edge-routing and /settings/installation/edge-routing redirect there.

Implementation behavior

• Custom hostnames can CNAME to edge.drip-apex.com so traffic enters the Cloudflare Worker.
• The Worker resolves the shop/domain, applies routing rules, and proxies or handles configured paths.
• Fallback origins and hostname validation prevent unverified traffic from being treated as a trusted shop domain.
• Runtime config keeps edge routing separate from normal SDK-only installs.

How to use it

• Use edge routing only when a storefront flow requires Worker mediation rather than SDK-only DOM changes.
• Validate DNS and custom hostname status before switching traffic.
• Keep origin settings current for each shop domain.
• Test preview and production domains separately.

When not to use it

• Do not use edge routing for ordinary DOM-only A/B tests that the SDK can handle.
• Do not route production domains before DNS validation and origin testing are complete.
• Do not mix Vercel domain ownership and Cloudflare custom hostname routing without checking which edge receives traffic.

Implementation source

• Worker code lives in packages/worker and Cloudflare routes are documented in project configuration.
• Dashboard install and edge pages use server-side domain-routing and edge-resolution services.
• Cloudflare custom hostnames and shop origin fields determine how requests are resolved.

Data and API

• Cloudflare Worker routes, custom hostname records, shop origin fields, and edge-routing verification state.
• Dashboard capabilities cover hostname discovery, DNS preflight, custom-hostname configuration, verification, and runtime resolution without exposing internal service paths.
• Worker observability is the main debugging source for edge routing.

Failure modes

• Hostname not active: DNS CNAME or validation TXT is missing.
• Origin loop or blank response: wrong origin field or Vercel/domain conflict.
• SDK works but edge route does not: these are separate deployment paths and must be verified independently.

Server-rendered variants

For a server-rendered storefront behind the customer-deployed Apex Edge Worker (version 1.1.16 or later), the Edge Worker forwards the visitor id and a signed assignment set to the origin so the origin can render variants without a hydration flicker. Let the edge decide and the origin render the variant. This avoids hydration replacing an edge DOM edit. The hosted snippet and Shopify pixel do not provide this origin handoff.

On HTML document GET requests, the worker replaces client-supplied copies of these headers:

• x-drip-visitor-id: the resolved drip_uid visitor ID.
• x-drip-assignments: the exact JSON envelope below. configRevision and assignmentEpoch are numbers or null. Assignments include decisions with no DOM mutations. An attribution-only decision includes "attributableOnly":true; retain it for attribution without rendering its treatment.
• x-drip-assignments-signature: lowercase hex HMAC-SHA-256 of the exact assignment header string, keyed with the worker's APEX_INGEST_TOKEN. It is absent when the token is not configured.

{"v":1,"configRevision":42,"visitorId":"visitor-id","assignments":[{"experimentId":"experiment-id","variationId":"variation-id","assignmentEpoch":7}]}

The assignment header is smaller than 4 KiB. If necessary, the worker sends the first assignments that fit and adds "truncated":true. Missing assignments mean render the default, including when the array is empty. The one-shot baseline reload sends an empty assignment set. Unavailable or incompatible config also falls back to an empty set. If header assembly fails, the origin request continues without handoff headers.

For a first-time visitor, the worker merges drip_uid=<id> into the upstream Cookie header while preserving other cookies. Non-HTML and non-GET requests receive no generated assignment headers. Existing edge rewriting and SDK injection remain active; configure server-rendered components so they do not compete with DOM mutations.

Trust boundary: an origin reachable without the worker must verify the signature or ignore these headers. Verify the exact received string before parsing it, using the same server-only APEX_INGEST_TOKEN. Never put the token in public runtime config. The signature authenticates the envelope, not freshness or a URL, so it is not authorization for prices, access, or other protected actions. Keep origin/CDN HTML caching partitioned by assignments or disabled; the worker's HTML cache separates assignment sets and does not store responses carrying Set-Cookie.

Verify the handoff

1. Put a temporary header-echo origin path behind your worker on a test domain. Request it with Accept: text/html, first without a cookie and then with Cookie: drip_uid=handoff-test.
2. Confirm both handoff headers, an upstream visitor cookie on the first request, and visitorId: "handoff-test" on the second. Verify the signature against the exact received JSON with HMAC-SHA-256 and the shared token. Do not expose a public echo endpoint containing real visitor data.
3. Send spoofed handoff headers and confirm the worker replaces them. Request JSON or POST a document request and confirm no handoff is generated.
4. Request GET /_drip/status on a hostname routed to the worker (use its workers.dev hostname if the storefront route only covers a path). Confirm workerVersion is 1.1.16 or later and originHandoff is "enabled".

See Render variants on the server for a Nitro middleware example.