How to Integrate RudderStack with Your Headless CMS

What is RudderStack?

RudderStack is a customer data platform that collects event data from websites, apps, servers, and cloud tools, then routes it to destinations like warehouses, analytics platforms, and marketing systems. Teams use it to standardize tracking, transform events, and send the same event stream to tools such as Snowflake, BigQuery, Amplitude, Mixpanel, and Google Analytics. Its core value is control over customer data pipelines, especially for teams that want warehouse-first analytics and fewer one-off tracking integrations.

Why integrate RudderStack with a headless CMS?

Content performance usually breaks down at the join. Your analytics tools know that a user viewed a page, clicked a CTA, or started a trial, but they often don't know which content type, campaign, author, region, topic, or experiment variant was involved. That leaves teams stitching reports together with URLs, spreadsheets, and naming conventions that drift after 3 launches.

Architecture overview

A typical Sanity and RudderStack integration starts when an editor publishes content in Sanity Studio. A Sanity webhook fires on the publish mutation and sends the document ID, type, and revision data to a secure endpoint, or to a Sanity Function if you want the logic to run inside Sanity's event system. The handler uses @sanity/client and a GROQ query to fetch the published document from the Content Lake, including only the fields RudderStack needs, such as _id, _type, title, slug, language, campaign reference, topic references, and publish date. The handler then calls RudderStack's Node SDK with a track call, using the source write key and data plane URL from your RudderStack JavaScript or HTTP source. RudderStack receives the event, applies any transformations you've configured, and routes it to destinations like Snowflake, BigQuery, Amplitude, Mixpanel, Google Analytics, or your own webhook destination. On the frontend, the end user reads the published content from Sanity-powered pages, and page or conversion events can include the same contentId so downstream tools can connect content operations to user behavior.

Common use cases

Step-by-step integration

1. 1

   Set up RudderStack

   Create or open a RudderStack workspace, add a JavaScript, Node.js, or HTTP source, copy the write key, and note your data plane URL, such as https://hosted.rudderlabs.com or your dedicated RudderStack data plane. Add at least one destination, like Snowflake, BigQuery, Amplitude, Mixpanel, or Google Analytics, so you can verify events end to end.

2. 2

   Define the analytics fields in Sanity Studio

   Model the content fields you want in analytics, not just the fields you render. For an article or landing page, that might include title, slug, language, author, topics, campaignId, funnelStage, persona, experimentId, and publishDate. Because Sanity schemas are code, these fields can be reviewed and versioned with the same pull request process as your tracking code.

3. 3

   Create a publish trigger

   Create a Sanity webhook that fires on create, update, and delete events for the document types you want to track. Use a GROQ-powered filter such as _type in ['article', 'landingPage', 'productPage'] to avoid sending unrelated mutations. If you don't want to run a separate server, use a Sanity Function to process the mutation and call RudderStack from server-side code.

4. 4

   Fetch the full document with GROQ

   Webhook payloads should stay small, so use the document ID from the mutation to fetch the current published version from the Content Lake. GROQ can project only the fields RudderStack needs and join references, for example topic titles, author names, and campaign slugs.

5. 5

   Send events to RudderStack

   Install @rudderstack/rudder-sdk-node, initialize it with the RudderStack source write key and data plane URL, and call track with a stable event name like Content Published. Put Sanity document IDs in properties.contentId so frontend events and warehouse queries can join on the same key.

6. 6

   Test the frontend and warehouse result

   Publish a test document in Sanity Studio, confirm the event appears in RudderStack Live Events, then check the destination table or analytics tool. On the frontend, send Page Viewed or CTA Clicked events with the same contentId, slug, and experimentId so you can connect publishing activity to user behavior.

Code example

A small webhook handler that receives a Sanity publish event, fetches the document with GROQ, and sends a RudderStack track event.

import type { VercelRequest, VercelResponse } from '@vercel/node';
import { createClient } from '@sanity/client';
import Analytics from '@rudderstack/rudder-sdk-node';

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
});

const rudder = new Analytics(
  process.env.RUDDERSTACK_WRITE_KEY!,
  process.env.RUDDERSTACK_DATA_PLANE_URL!
);

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  const { _id, transition } = req.body;
  if (!_id || transition !== 'appear') return res.status(202).json({ skipped: true });

  const doc = await sanity.fetch(`*[_id == $id][0]{
    _id,
    _type,
    title,
    'slug': slug.current,
    language,
    publishDate,
    'topics': topics[]->title,
    'author': author->name,
    campaignId,
    experimentId
  }`, { id: _id.replace('drafts.', '') });

  if (!doc) return res.status(404).json({ error: 'Document not found' });

  rudder.track({
    userId: 'sanity-system',
    event: 'Content Published',
    properties: {
      contentId: doc._id,
      contentType: doc._type,
      title: doc.title,
      slug: doc.slug,
      language: doc.language,
      topics: doc.topics,
      author: doc.author,
      campaignId: doc.campaignId,
      experimentId: doc.experimentId,
      publishDate: doc.publishDate
    }
  });

  await rudder.flush();
  return res.status(200).json({ sent: true });
}

How Sanity + RudderStack works

CMS approaches to RudderStack

Keep building

Explore related integrations to complete your content stack.