If you need to build a reliable integration that keeps a Notion database in sync with another system (or exposes a deterministic tool your Notion AI can call), Notion Workers are the developer-platform feature to reach for: you write a small TypeScript program, deploy it with the Notion CLI, and Notion runs it on their hosted runtime.

Notion Workers run TypeScript code on Notion’s hosted runtime. Photo by Chris Ried on Unsplash

What are Notion Workers?

Notion Workers are small Node/TypeScript programs that run on Notion’s infrastructure. They’re designed for three common jobs:

Sync external data into Notion on a schedule (so Notion becomes the system people work from, even if the source of truth lives elsewhere).
Create custom tools that Notion Custom Agents can call, when there isn’t an off-the-shelf connector or MCP server for the system you need.
Receive webhooks from external services to trigger Notion workflows.

In short: Workers are custom code that Notion hosts and runs for you, with no servers to manage.

Workers vs. custom agents vs. automations vs. MCP (quick comparison)

If you’re trying to pick the right primitive, this is the simplest mental model:

Use Workers when…

You need to sync data from an external API into a Notion database (with backfill + incremental updates).
You need custom logic (transformations, deduping, paging, rate limiting, retries) that’s hard to express in point-and-click automation tools.
You want to expose deterministic tools (JSON in/out) for Notion AI to call.

Use custom agents when…

The work is primarily reasoning + writing + decisions on top of your existing Notion knowledge (docs, tasks, meeting notes, etc.).
You want an agent that can take actions inside Notion (create pages, update properties, comment, summarize) without standing up a code runtime.

Use database automations when…

The workflow is inside Notion and can be expressed as a trigger + a few structured actions (e.g., “when Status becomes Done, set Completed Date”).
You don’t need external API calls or custom code.

Use MCP when…

You’re connecting an external AI (like Claude) to a system via a standard tool interface.
You want a reusable “toolbelt” pattern for an agent to interact with an app, where the MCP server already exists (or you can run your own).

Workers can complement all of the above: they can power the sync layer, add tools, or act as a bridge via webhooks.

Prerequisites (before you start)

A Notion workspace where you can create and deploy Workers.
Node + npm (use a current LTS release).
A plan for where secrets live (environment variables) and who owns the repo (Git).

Step 1: Install the Notion CLI

Notion’s CLI is ntn. It handles authentication, scaffolding, deploying, and managing Workers. Install it with curl -fsSL https://ntn.dev | bash.

High level workflow:

Install ntn
Authenticate
Scaffold a worker project
Develop locally
Deploy and monitor

Step 2: Scaffold a new Worker project

Scaffold a new project with ntn workers new my-worker, then cd my-worker. This gives you the right folder structure and config from the start.

The scaffold gives you src/index.ts, which exports a single Worker instance. Every capability is registered on that instance:

Syncs, tools, and webhooks (worker.sync, worker.tool, worker.webhook)
It defines the Notion-managed database outputs (for syncs)
Each capability’s key, which you use later to run, trigger, or pause it from the CLI

Step 3: Pick a Worker type (sync, tool, or webhook)

Most Worker projects start by choosing one capability:

A) Sync Worker (most common)

A sync Worker typically has two pieces:

Backfill sync for historical data
Delta sync that runs on a schedule (every 30 minutes by default, configurable) to pull changes

A sync is the right fit when:

There’s an external system of record (CRM, billing system, ticketing system, internal DB)
You want Notion to be the operational view
You want Notion AI to be able to reason over up-to-date data without leaving Notion

B) Tool Worker (for Notion AI)

A tool Worker exposes a function (with structured inputs/outputs) that Notion AI can call. This is the “give your agent a new capability” pattern.

Examples:

“Look up a customer in our billing system and return plan + renewal date”
“Validate an address and return a normalized version”
“Calculate a quote given a ruleset”

C) Webhook Worker (bridge external events into Notion)

Webhook Workers are the best fit when the outside world needs to “poke” Notion:

A form submission arrives
A call recording finishes processing
A ticket is escalated
A Stripe event fires

Step 4: Develop with a coding agent (without leaking secrets)

Workers were built to be coded with an AI coding assistant, but you still need a clean boundary between “code generation” and “secret handling.”

Recommended pattern:

Keep all secrets in environment variables
Never paste raw tokens into prompts
Use a .env file locally (ignored by Git) and store production secrets with the CLI so the Worker runtime manages them

Step 5: Deploy your Worker

Deploy with ntn workers deploy from the project directory. The first time, the CLI prompts you to connect your Notion workspace. It will:

Build the project
Upload it
Register/update the Worker in your workspace

From there, you can validate:

the Worker is healthy
sync outputs are writing into the expected Notion database (ntn workers sync status shows live run status)
tools and webhooks behave as expected (ntn workers exec runs any capability on demand)

Security best practices (what actually matters)

If a Worker is going into production, for your own team or a client, this is the checklist we hold to:

Use environment variables for all secrets

API keys, OAuth client secrets, tokens, and signing secrets should only exist in:

your secrets manager, and/or
the Worker’s environment variables

Use least-privilege access

Give the Worker only the scopes it needs.

If it only reads Salesforce, don’t give it write access.
If it only needs one database, don’t connect it to the entire workspace.

Put the Worker in version control

Use Git so ownership and maintenance are explicit. If an outside developer or agency builds it:

keep the repo under your organization (or have it transferred to you)
document how to rotate secrets and redeploy

Document the operational contract

Write down, in a single place:

what the Worker syncs
how often it runs
what rate limits exist
what “good” looks like (row counts, error thresholds)
who owns alerts and maintenance

Pricing: how to estimate Worker cost

Workers are usage-based and bill against Notion credits. To estimate cost:

Estimate runs per month
Multiply by the typical cost per run: about $0.0023, or roughly 4,348 runs per 1,000 Notion credits ($10) (as of October 2026 — check current pricing)
Add a buffer for backfills, retries, and unexpected scale

The comparison that matters is human time. A sync every 15 minutes runs about 2,880 times a month, roughly $6.62 at the typical rate, which is less than an hour of someone babysitting a fragile integration. Workers also cost less per run than Notion Custom Agents, because they don’t make AI decisions.

How to explain Workers to your team

If you need a simple way to explain Workers to leadership or non-technical teammates:

Workers let you connect Notion to any system with an API.
They keep data synced into Notion so the team works from one place.
They can also add tools that Notion AI can call, so workflows become smarter over time.
Notion hosts the runtime, so you don’t need to manage servers.

If you want help scoping a Worker (sync vs. tool vs. webhook), our Notion team can map your systems and build a first version quickly.

When you should not use Workers

Workers aren’t always the answer. Skip them when:

A native connector or a no-code tool already solves it reliably
The workflow is entirely within Notion and can be handled by database automations
The integration is one-off and doesn’t justify owning and maintaining code

Next step: get a Worker scoped correctly

Most Worker projects go sideways for one of two reasons:

unclear ownership (who maintains it?)
unclear data contract (what is the source of truth, and what fields “win”?)

If you want a fast, concrete plan for a Worker in your workspace, start with a short scoping call.

Talk to a Connex automation expert

Automate OneDrive Excel loads to SQL Server with Power Automate Fix Missing Zoom Meeting IDs in Automation Pipelines

Notion Workers: what they are + how to build and deploy one