How to Integrate Optimizely with Your Headless CMS

What is Optimizely?

Optimizely is a digital experience platform used for web experimentation, feature experimentation, personalization, and digital experience analytics. Product, growth, marketing, and engineering teams use Optimizely to run A/B tests, route traffic, target audiences, and measure conversions across websites and apps. Its experimentation tools are widely used by mid-market and enterprise teams that need controlled rollouts and measurable content or product changes.

Why integrate Optimizely with a headless CMS?

Experimentation gets messy when content lives in one place and test logic lives somewhere else. A landing page headline changes in your content system, but the A/B test in Optimizely still points to last week’s copy. A personalization campaign targets “enterprise visitors,” but the actual offer text is buried in a page field that nobody wants to paste into another UI.

Connecting Optimizely to a headless CMS category system solves that split. With Sanity’s AI Content Operating System, content is structured as typed JSON in the Content Lake, so Optimizely can receive specific fields like headline, CTA label, audience key, slug, experiment key, and variation ID. GROQ selects the exact payload, webhooks fire on publish, and Functions can run the sync logic without a separate worker app.

The alternative is manual work. Someone copies variation copy into Optimizely, another person updates the website, and a third person checks whether the experiment still matches the published page. That can work for one test. It breaks down when you’re running 20 campaigns across 6 locales, 4 audience segments, and multiple frontend surfaces.

Architecture overview

A typical Sanity and Optimizely integration starts with structured content in the Content Lake. Editors create experiment-ready documents in Sanity Studio, for example a campaign with references to variants, audience segments, locale-specific copy, and Optimizely IDs. When a document is published, a Sanity webhook can fire with a GROQ filter such as _type == "experimentVariant" && defined(optimizely.featureId). The webhook calls a Sanity Function or your own middleware. That server-side code fetches the published document from the Content Lake using GROQ, joins referenced audience and campaign documents, maps the result to Optimizely fields, and calls the Optimizely REST API with a bearer token. For Optimizely Feature Experimentation, the sync often updates a feature variable or variation metadata with a Sanity content ID, headline, CTA, or JSON payload. For Optimizely Web Experimentation, the sync may update experiment or variation configuration while the page still renders content from Sanity. At runtime, the frontend uses the Optimizely Web snippet or Feature Experimentation SDK to decide which variation a visitor should see, then renders the matching Sanity content to the end user.

Common use cases

Step-by-step integration

1. 1

   Set up Optimizely

   Create an Optimizely Web Experimentation or Feature Experimentation project, add your environments, and copy the project ID, SDK key, and REST API personal access token. If you’re using Feature Experimentation, create a flag and note the feature ID, variable ID, and variation keys you’ll map to Sanity documents.

2. 2

   Install the required packages

   In your sync service or Sanity Function, install @sanity/client for Content Lake reads. In your frontend, install @optimizely/optimizely-sdk if you’re using Feature Experimentation decisioning, or add the Optimizely Web snippet if you’re running browser-based experiments.

3. 3

   Model experiment content in Sanity Studio

   Create schema fields for experimentKey, featureId, variableId, variationKey, audienceKey, locale, headline, image, CTA label, CTA URL, and status. Keep Optimizely IDs close to the content so editors can see which campaign or flag a variant feeds.

4. 4

   Create the publish trigger

   Add a Sanity webhook with a GROQ filter such as _type == "experimentVariant" && defined(optimizely.featureId). Send published mutations to a Sanity Function or webhook listener, and use a shared secret to verify the request.

5. 5

   Call the Optimizely API

   Fetch the full Sanity document with GROQ, map fields into the shape your Optimizely flag, variable, or experiment expects, and call the Optimizely REST API using a bearer token. Keep large rich text bodies in Sanity when possible, and send content IDs or short JSON values to Optimizely.

6. 6

   Test the frontend experience

   Use Optimizely’s preview or forced-variation tools to check each variant. Then confirm the frontend decision flow: Optimizely returns a variation key, your app fetches the matching Sanity content, and analytics events record the conversion you care about.

Code example

A small webhook handler that receives a Sanity publish event, fetches the current content with GROQ, and updates an Optimizely Feature Experimentation variable through the Optimizely REST API.

import { createClient } from '@sanity/client'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-01-01',
  token: process.env.SANITY_READ_TOKEN!,
  useCdn: false
})

export async function POST(req: Request) {
  const event = await req.json()
  const id = event._id.replace('drafts.', '')

  const variant = await sanity.fetch(`
    *[_id == $id][0]{
      _id,
      headline,
      ctaLabel,
      ctaUrl,
      variationKey,
      optimizely{featureId, variableId}
    }
  `, { id })

  if (!variant?.optimizely?.featureId) {
    return Response.json({ skipped: true })
  }

  const value = JSON.stringify({
    sanityId: variant._id,
    variationKey: variant.variationKey,
    headline: variant.headline,
    ctaLabel: variant.ctaLabel,
    ctaUrl: variant.ctaUrl
  })

  const res = await fetch(
    `https://api.optimizely.com/v2/features/${variant.optimizely.featureId}/variables/${variant.optimizely.variableId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${process.env.OPTIMIZELY_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ default_value: value })
    }
  )

  if (!res.ok) {
    throw new Error(`Optimizely API error: ${res.status} ${await res.text()}`)
  }

  return Response.json({ synced: variant._id })
}

How Sanity + Optimizely works

CMS approaches to Optimizely

Keep building

Explore related integrations to complete your content stack.