How to Integrate Wistia with Your Headless CMS

What is Wistia?

Wistia is a video hosting and marketing platform used by B2B marketing, education, product, and sales teams to host videos, customize players, collect leads, and analyze engagement. Its core capability is managing business video assets with embeddable playback, metadata, captions, channels, and viewer analytics. Teams often use Wistia when they need more control over branded video experiences than a public video platform provides.

Why integrate Wistia with a headless CMS?

Video usually sits in one place, while page copy, product details, campaign messaging, localization, and publish workflows sit somewhere else. That gap creates small but expensive problems: an editor pastes the wrong Wistia embed, a product tutorial ships with an outdated description, or a webinar page publishes before the video is ready.

Architecture overview

A typical Wistia integration starts with editors working in Sanity Studio. A video content type includes fields like title, description, Wistia hashed ID, Wistia project ID, transcript, thumbnail override, related content references, and publish status. When an editor publishes or updates a video page, a Sanity webhook fires on that mutation. The webhook payload includes the document ID, not the full integration payload. A webhook listener or Sanity Function then uses @sanity/client and GROQ to fetch only the fields Wistia needs, including referenced product names or campaign tags. The server-side code calls Wistia's Data API, for example PUT https://api.wistia.com/v1/medias/{hashed_id}.json, with an API token in the Authorization header to update media name, description, or other supported metadata. On the frontend, your site renders the Wistia embed using the hashed ID, or requests Wistia oEmbed data from https://fast.wistia.com/oembed for the public embed HTML. The end user sees the current video, copy, CTA, and surrounding structured content from one publish workflow.

Common use cases

Step-by-step integration

1. 1

   Set up Wistia access

   Create or choose a Wistia account, confirm the project where videos will live, and create an API token from Wistia's API access settings. Store the token as a server-side environment variable, never in browser code.

2. 2

   Install the web tooling

   Add @sanity/client to your webhook service or app. If you're rendering Wistia embeds in the browser, include Wistia's player script from https://fast.wistia.com/assets/external/E-v1.js or use Wistia oEmbed server-side.

3. 3

   Model Wistia fields in Sanity Studio

   Create a video schema with fields such as title, slug, description, wistiaHashedId, wistiaProjectId, transcriptSummary, thumbnailAlt, relatedProducts, and publishToWistia. Use validation so editors can't publish a Wistia module without a hashed ID.

4. 4

   Create the sync trigger

   Add a Sanity webhook that fires on create, update, and publish events for your video document type. For server-side processing without another queue or cron job, put the same logic in a Sanity Function.

5. 5

   Call Wistia's API

   When the webhook fires, fetch the latest Sanity document with GROQ, then call Wistia's Data API to update the matching media record. Start with metadata sync before adding upload flows, because upload workflows need larger file handling and retry logic.

6. 6

   Test the frontend experience

   Render a page with the Wistia hashed ID from Sanity, confirm the player loads, test draft and published states, and verify that a Sanity publish updates Wistia metadata within one webhook run.

How Sanity + Wistia works

CMS approaches to Wistia

Keep building

Explore related integrations to complete your content stack.