How to Integrate Sentry with Your Headless CMS

What is Sentry?

Sentry is an application monitoring platform for error tracking, performance monitoring, session replay, and release health. Engineering teams use it to capture exceptions, group related issues, trace slow transactions, and connect production errors back to code releases. It's one of the most widely used tools in Monitoring & Observability for web, mobile, backend, and serverless applications.

Why integrate Sentry with a headless CMS?

Content can cause production incidents. A missing image asset can throw a rendering error, a bad slug can break routing, a malformed Portable Text block can fail a serializer, and an unexpected reference can turn a product page into a 500. Without a connection between your content system and Sentry, engineers see the stack trace, but not the content change that triggered it.

Architecture overview

A typical Sanity and Sentry integration starts with a publish event in the Content Lake. A Sanity webhook fires on create, update, or publish, often with a small projection that includes the document ID and mutation type. A Sanity Function or webhook endpoint receives that payload, uses @sanity/client to run a GROQ query for the exact fields needed, such as _id, _type, title, slug.current, locale, owner, release name, and referenced campaign. The server-side handler then calls Sentry through the SDK, such as @sentry/node or @sentry/nextjs, to capture an info-level content event with tags and context. If you also use Sentry Releases, the handler can call Sentry's REST API to create a release or deploy marker for a content release. On the frontend, the Sentry browser or framework SDK captures runtime errors and performance traces. When an end user hits a broken route, the Sentry issue includes both code context and content context, so the team can find the source document in Sanity Studio, fix it, republish, and confirm the issue stops occurring.

Common use cases

Step-by-step integration

1. 1

   Set up Sentry for your app

   Create a Sentry organization and project for your framework, such as Next.js, Node.js, or React. Copy the project DSN, install the matching SDK, and confirm Sentry receives a test exception. If you want release or deploy markers, create an auth token with release-related project permissions.

2. 2

   Add content fields that help incident response

   In Sanity Studio, model fields that engineers will need in Sentry: title, slug, locale, owner, content type, campaign, release name, feature flag, and canonical route. Keep these as typed fields so GROQ can query them directly.

3. 3

   Create a publish trigger

   Use a Sanity webhook or Function that runs on publish events. Configure a small webhook projection, such as {"_id": _id, "_type": _type}, then fetch the full context server-side. In production, verify the webhook signature before calling external services.

4. 4

   Fetch the exact content context with GROQ

   Use @sanity/client with useCdn: false so the handler reads fresh content. Query only what Sentry needs, including joined references like owner->email or campaign->slug.current.

5. 5

   Send events to Sentry

   Use the Sentry SDK to capture an info-level message with tags and context, or call Sentry's Releases API if your content release should appear alongside code deploys. Keep tag values short because Sentry tags are meant for filtering, not full document payloads.

6. 6

   Test the full incident path

   Publish a test document, confirm the webhook fires, verify the event appears in Sentry with Sanity tags, then trigger a frontend error on that route. The final issue should show both the stack trace and the content fields needed to fix it.

Code example

import {createClient} from '@sanity/client'
import * as Sentry from '@sentry/nextjs'

Sentry.init({dsn: process.env.SENTRY_DSN})

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

export async function POST(req: Request) {
  const body = await req.json()

  const doc = await sanity.fetch(
    `*[_id == $id][0]{
      _id,
      _type,
      title,
      "slug": slug.current,
      "owner": owner->email
    }`,
    {id: body._id}
  )

  if (!doc) return Response.json({ok: false}, {status: 404})

  Sentry.withScope((scope) => {
    scope.setTags({
      source: 'sanity',
      documentType: doc._type,
      slug: doc.slug || 'no-slug',
    })
    scope.setContext('sanityDocument', doc)
    Sentry.captureMessage(`Content published: ${doc.title}`, 'info')
  })

  await Sentry.flush(2000)
  return Response.json({ok: true})
}

How Sanity + Sentry works

CMS approaches to Sentry

Keep building

Explore related integrations to complete your content stack.