Notion

Productivity OAuth, or a connection token you paste Windmill docs

Search, read and write Notion pages, databases, blocks, comments and files from any Windmill script, flow or app. Read pages as Markdown, append to or duplicate them, create databases and rows and query them with filters, upload files, and react to Notion webhooks through a Windmill HTTP route.

Set up in 3 steps

Connect with OAuth

Open Resources, click Add a resource/API and pick notion from the OAuth APIs list, then click Connect. On Notion's consent screen, choose the workspace and select the pages the scripts should reach. Subpages inherit access. The connection acts as you, and its token does not expire.

Or paste a connection token

In the Notion developer portal (notion.so/developers), create a connection with the API token auth type and copy its token. Grant it pages in its Content access tab, or from a page's ••• menu → Connections: without that step every call answers 404. Then add a notion resource and paste the token. A personal access token also works, but it expires.

Turn on the capabilities you need

In the connection's Configuration tab, Read comments, Insert comments and user information are off by default. Turn them on if you will use the comment or user scripts.

Scripts

Building blocks, if none of the projects above fit. Fork one, run it, or call it as a step inside your own flow.

Submit a script →

Trigger flows from Notion

Notion is not only a destination. These inbound paths are supported today.

Notion webhooks on an HTTP route

Create a Windmill HTTP route with no authentication, then add a webhook subscription in your connection's Webhooks tab pointing at it and pick the events (page.created, page.content_updated, page.properties_updated, comment.created, database events…). Notion first posts a verification_token: copy it from the route's run and paste it back in Notion. Then switch the route to Signature authentication with a Custom scheme — header X-Notion-Signature, sha256, hex, prefix sha256=, secret the verification token — so only signed events start your flow.

Database automations

A database automation's Send webhook action can call the same HTTP route when a row is added or a property changes, with no connection subscription needed.

Resource type

The shape of the credential every script on this page expects.

notion

View raw schema →

Field	Type	Required	What it is
token	string	Yes	Filled automatically when you connect with OAuth. To paste one instead: the API token of an internal connection (ntn_…) or a personal access token, both created in the Notion developer portal at https://www.notion.so/developers. A connection token only reaches the pages granted to it under Content access.

Questions

A script returns 404, or cannot find my page

The page was never granted to the connection. Add it under Content access in the developer portal, or from the page's ••• menu → Connections. A connection sees only what it has been given.

Database id or data source id?

Querying and adding rows takes the data source id. The id in a database URL is the database id: run Retrieve Database on it and use data_sources[0].id, or pick the database from the dropdown in Query Data Source.

Comments or users fail with restricted_resource

The connection lacks that capability. Turn on Read comments, Insert comments or user information in the connection's Configuration tab: they are off by default.

There is no Connect button on my instance

Self-hosted instances need an admin to register a Notion OAuth client once. In the Notion developer portal, create a connection with the OAuth auth type, add the redirect URI https://<your instance>/oauth/callback/notion, and paste its client ID and secret under Instance settings → OAuth → notion. Until then, paste a connection token.

Why no polling trigger?

Notion pushes changes as webhooks, which are quicker and lighter than polling for last_edited_time. Point them at a Windmill HTTP route as described above.

Is my token stored on the hub?

Never. It lives only in your own Windmill workspace, encrypted at rest.

Set up in 3 steps

Connect with OAuth

Or paste a connection token

Turn on the capabilities you need

Scripts

Append Block Children

Upload File

Update Data Source

Update Block

Move Page to Trash or Restore

Retrieve User

Retrieve Page Property Item

Retrieve Database

Retrieve Data Source

List Comments

Get Current User

Duplicate Page

Delete Block

Create Page

Create Database

Create Comment

Append Markdown to Page

Query Data Source

Update Page Properties

Retrieve Block Children

Search

List Users

Get Page as Markdown

Retrieve Block