How to Integrate Amplitude with Your Headless CMS

What is Amplitude?

Amplitude is a digital analytics platform used by product, growth, and data teams to understand how people move through apps and websites. It tracks events, analyzes funnels and retention, builds behavioral cohorts, and supports experimentation through Amplitude Experiment. It’s widely used by SaaS, media, marketplace, and commerce teams that need product analytics tied to real user behavior.

Why integrate Amplitude with a headless CMS?

Content performance gets messy when your analytics events know that someone viewed /pricing, but they don’t know which content version, campaign, audience, author, or experiment variant was on that page. Teams end up joining Amplitude exports with spreadsheets, release notes, and URL conventions. That works for 20 pages. It breaks when you have 2,000 articles, localized landing pages, mobile screens, and AI-generated content variants.

Connecting Amplitude to a headless CMS lets you send structured content metadata into analytics events. A page view can include content_id, content_type, slug, funnel_stage, audience, locale, and experiment_key. A publish event can show when a content change went live, so product teams can compare conversion before and after the change instead of guessing from deploy timestamps.

With Sanity, the Content Lake holds typed JSON, so you don’t need to scrape HTML or parse rich text blobs to build Amplitude payloads. GROQ selects only the fields Amplitude needs, webhooks fire on publish, and Functions can run the server-side call to Amplitude without a separate worker. The trade-off is that you still need a clear event taxonomy. If one team sends contentId and another sends content_id, Amplitude will treat them as different properties.

Architecture overview

A typical Sanity and Amplitude integration starts when an editor publishes or updates content in Sanity Studio. The content mutation lands in the Content Lake, then a Sanity webhook fires with the document ID, type, and operation. A webhook handler or Sanity Function receives that event and uses @sanity/client to fetch the full document with a GROQ query, including joined fields like category, campaign, locale, author, and experiment metadata. The server-side handler then calls Amplitude’s HTTP V2 API at https://api2.amplitude.com/2/httpapi, usually with an event such as Content Published, Content Updated, or Content Archived. The payload should include a stable device_id or user_id, an event_type, a time value in milliseconds, and event_properties that hold Sanity fields such as _id, _type, slug.current, title, content_type, and analytics_key. You usually shouldn’t send the full article body to Amplitude. Send identifiers and metadata, then keep the full content in the Content Lake. On the frontend, the user sees the content delivered from Sanity to web, mobile, or another channel. Your client-side Amplitude SDK can send Viewed Content, CTA Clicked, Signup Started, or Purchase Completed events using the same content_id and analytics_key. That gives product teams a shared thread from publish event, to exposure, to conversion in Amplitude.

Common use cases

Step-by-step integration

1. 1

   Create an Amplitude project and get keys

   In Amplitude, create or select a project, then copy the project API key from Settings. Use the HTTP V2 API for server-side content events, and install @amplitude/analytics-browser on the frontend for user behavior events.

2. 2

   Model analytics fields in Sanity Studio

   Add fields such as analyticsKey, funnelStage, audience, locale, campaign, experimentKey, and experimentVariant to the relevant Sanity schema. Keep these fields structured, not embedded in body copy, so they can be queried and reused.

3. 3

   Create a publish webhook or Sanity Function

   Configure a Sanity webhook to trigger on create, update, and delete events for the document types you care about, such as article, landingPage, productGuide, or campaignPage. Point it to a webhook handler, or use Functions if you want the sync logic to run inside Sanity’s server-side event system.

4. 4

   Fetch the exact content payload with GROQ

   Use @sanity/client and a GROQ projection to fetch only the fields Amplitude needs. Include references such as category, author, campaign, or product so Amplitude events don’t depend on a second lookup later.

5. 5

   Send events to Amplitude

   Post to Amplitude’s HTTP V2 API with api_key and an events array. Each event needs user_id or device_id, event_type, time, and event_properties. Use insert_id to reduce duplicate events when a webhook retries.

6. 6

   Test the frontend and analytics views

   Load a published page, send a Viewed Content event from the browser SDK with the same content_id, then confirm the event in Amplitude’s event views. Build a funnel such as Viewed Content, CTA Clicked, Signup Started, and Activated to validate the full path.

How Sanity + Amplitude works

CMS approaches to Amplitude

Keep building

Explore related integrations to complete your content stack.