How to Integrate Asana with Your Headless CMS

What is Asana?

Asana is a work tracking and collaboration platform used by marketing, product, operations, and content teams to plan projects, assign tasks, set due dates, and track progress. Teams use Asana to coordinate work across boards, lists, timelines, calendars, approvals, comments, and project portfolios. Its API lets you create tasks, update custom fields, add comments, attach work to projects, and connect Asana to the systems where work starts.

Why integrate Asana with a headless CMS?

Content work usually doesn’t start and end in one place. A marketer publishes a campaign brief, a legal reviewer needs a task, a designer needs a due date, and a localization lead needs to know when the source page changes. If those handoffs live in Slack threads, spreadsheets, or someone’s memory, work gets missed. Connecting Asana to your headless CMS turns content events into trackable work, like creating a task when a landing page enters review, updating an Asana custom field when a release date changes, or adding a comment when a page is published.

This works best when the headless CMS gives you structured content, not page blobs. With Sanity, content in the Content Lake is typed JSON, so a workflow can read fields like title, campaign, locale, owner, reviewStatus, and publishAt directly. GROQ selects only the fields Asana needs, webhooks fire on publish or update events, and Functions can run the server-side sync without a separate queue worker or cron job.

The disconnected version is slower and messier. Someone exports a CSV, renames fields, pastes task titles into Asana, adds due dates by hand, and then repeats the process when the brief changes. That can work for 10 pages a month. It breaks down when you’re coordinating 200 product pages, 8 locales, 4 approvers, and multiple launch dates.

Architecture overview

A typical Sanity and Asana integration starts when an editor creates, updates, or publishes a document in Sanity Studio. A GROQ-powered webhook filters for the content types and workflow states you care about, for example only campaign pages where reviewStatus changes to "ready_for_review". The webhook sends the document ID to a Sanity Function, or to your own API route if you prefer to run middleware elsewhere. The Function uses @sanity/client to fetch the latest version from the Content Lake with a GROQ query. That query can include references, so the sync can pull the page title, slug, campaign name, owner email, locale, publish date, and existing Asana task ID in one request. The Function then calls Asana’s REST API through the official Node SDK using a personal access token or OAuth token. It can create a task in a specific Asana project, assign it to a user by GID, set due_on from the Sanity publish date, write notes with a Sanity Studio link and preview URL, and populate custom fields such as content type, locale, or review status. The end user sees the result in Asana as normal work. Reviewers get assigned tasks, project managers see status in a board or timeline, and editors can keep working in Sanity Studio. The trade-off is that you need to decide ownership rules up front. For example, should Asana be the source for task completion while Sanity owns publish status, or should task completion write back into Sanity? Pick one direction for each field to avoid conflicting updates.

Common use cases

Step-by-step integration

1. 1

   Set up Asana access

   Create or choose an Asana workspace, project, and any custom fields you want to set, such as content type, locale, review status, or launch date. For local testing, create a personal access token in Asana under My settings, Apps, Developer apps. For production installs across many users, use Asana OAuth instead. Install the SDK with npm install asana.

2. 2

   Model the workflow fields in Sanity Studio

   Add fields that map cleanly to Asana, such as title, slug, owner, reviewStatus, publishAt, locale, campaign, and asanaTaskGid. If owners are Sanity references, include the Asana user GID or email on the person document so your sync can assign tasks.

3. 3

   Create a GROQ-powered trigger

   Configure a Sanity webhook for the document types you want to sync, such as campaignPage, article, or releaseNote. Filter for useful events instead of every edit, for example publish events or updates where reviewStatus == "ready_for_review".

4. 4

   Run server-side sync logic

   Use a Sanity Function for server-side processing without standing up a separate service. The Function receives the webhook payload, fetches the current document from the Content Lake with GROQ, formats the task payload, and calls Asana.

5. 5

   Call Asana’s API

   Use Asana’s Tasks API to create or update tasks in a target project. Set name, notes, assignee, due_on, projects, and custom_fields. Store the returned task GID back on the Sanity document if you want later updates to target the same task.

6. 6

   Test the editorial and frontend flow

   Publish or update a test document in Sanity Studio, confirm the task appears in Asana, verify assignments and dates, and open the preview URL from the task. Then test failure cases, such as missing owners, invalid tokens, deleted Asana projects, and duplicate webhook retries.

How Sanity + Asana works

CMS approaches to Asana

Keep building

Explore related integrations to complete your content stack.