Notion

Your Notion pages and databases — to open a case from an email, file its attachments there and write the follow-up.

A Notion connection lets the Notion node work with your pages and databases: open a case from an email, file its attachments, write the follow-up, comment, search. The same connection feeds two triggers: Notion entry changed, which checks a database at a regular interval, and Notion — event, which receives Notion webhooks.

The connection holds a Notion integration token. It is encrypted at rest, applied by the server at call time, and never appears in a workflow. Every call is sent with the Notion API version fixed by the product (Notion-Version: 2026-03-11); it cannot be changed per connection.

At a glance

• Identifier: notion
• Family: Service
• Set up by: A member (personal) or an administrator (shared with the organisation)
• Authentication: API key or token
• Credential type: service:notion
• Official API documentation: https://developers.notion.com/reference/intro
• API base URL: https://api.notion.com
• Rate limit applied by Mankomail: 180 requests per minute and per connection; up to 4 attempts on a 429 or a 5xx
• Webhook signature: X-Notion-Signature header, HMAC-SHA256 of the raw body
• Connection test: Yes

Step by step

The same steps are shown in the connection form of the app.

1. Open https://www.notion.so/profile/integrations, then “New integration” (or “New token”).
2. Give it a name, pick the workspace, then confirm with “Save” — the token (ntn_…) is shown only once.
3. In the “Capabilities” tab, turn on: Read content, Update content, Insert content, Read comments, Insert comments, and “User information with email”.
4. Paste the token below, then — the step no one can skip — SHARE your pages: in Notion, open the root page or database → “···” menu → “Connections” → “Add connections” → your integration. Sub-pages inherit the sharing.
5. For a Notion webhook: publish the workflow, copy the URL shown in the “Notion — event” trigger panel, and create the subscription in Notion’s developer portal. Notion then sends a verification token to that URL, which we store in this connection: reopen it, click “Show the received token”, copy it and paste it into Notion (“Verify”).

Connection fields

Field	Kind	Required	Notes
Integration token (token)	Secret — never shown again	Yes	It only sees the pages you explicitly share with the integration. A personal access token, by contrast, sees everything you see — keep it for a dedicated service account.
Webhook verification token (verificationToken)	Secret — never shown again	No	Optional, and filled in automatically: Notion sends it to the trigger URL when the subscription is created. It then acts as the signing key. Clear it to receive a new one.

Before you start

• Create the integration from https://www.notion.so/profile/integrations in the workspace the workflows will use. You must be allowed to create integrations in that workspace.
• An internal integration sees nothing until pages are shared with it. This is the number-one cause of empty lists and object_not_found errors. In Notion, open the root page or database → ··· menu → Connections → Add connections → your integration. Sharing is inherited by sub-pages, so share the highest page that makes sense.
• A personal access token (PAT) is also accepted. It sees everything its owner sees, without per-page sharing — keep it for a dedicated service account. It cannot list workspace members.
• A relation to another database is readable only if that other database is shared with the integration too; otherwise its value comes back empty, without an error.

Permissions

In Notion these are the integration’s Capabilities. Turn on what the nodes you use need:

Capability	Used for
Read content	Every read: Search, Query entries, Entries created or edited since…, Read the schema, Get a page, List blocks, Read the content as Markdown, the editor’s pickers, and the Notion entry changed trigger. Required.
Update content	Update the properties, Move to trash / restore.
Insert content	Create an entry, Create a page, Append blocks, Write content as Markdown, Upload the attachments.
Read comments	List comments. Optional.
Insert comments	Create a comment. Optional.
User information with email	List people with their email (for people properties) and lets the connection test display the workspace name. Optional, but without it the member picker fails.

A missing capability shows up as a 403 when the workflow runs, not when the connection is saved.

Databases and data sources

Since Notion API version 2025-09-03, a database is a container that holds one or more data sources, and the data source carries the schema. Almost every endpoint wants the data source id, not the database id; the two are not interchangeable.

The editor handles the cascade: choose the Database (the name you see in Notion, its id or its pasted URL), then the Data source — which has a single entry in nearly every case — then the properties. Property pickers return the property name, which is what Notion expects in filters, sorts and writes.

Notion search is indexed and slightly delayed: a page shared a moment ago may not appear in a picker yet. Paste its URL or id instead.

Add the connection

1. Open Connections. In the Third-party services section, find the Notion card and click Connect.
2. Give the connection a Name and choose the Scope: Personal (only you can see and use it) or Organisation (the whole organisation uses it; only an administrator can create one).
3. Paste the Integration token (ntn_…). Leave Webhook verification token empty unless you use the Notion — event trigger. Click Create the connection.
4. Share your pages with the integration in Notion (see above).
5. Back in the list, click Configure on the new connection, then Test the connection.

The test runs in two steps:

1. GET /v1/users/me validates the token and returns the workspace name, shown in the result. If the User information capability is off, Notion answers 403; the test goes on without a name.
2. POST /v1/search with a page size of 1 checks that something is shared with the integration. If nothing is, the test fails — the token is valid, but every operation would fail with a 404. The message reads “the service answered something other than what we expected”: share a page or database, then test again.

In a node, pick the connection in Notion connection, then the database and data source, or a page. Delete is refused while a published workflow uses the connection.

Webhooks

Two triggers react to Notion changes. Both deliver their data under data.notion, and neither has a triggering email.

Polling: Notion entry changed

Notion entry changed (trigger.notion_changes) needs no setup in Notion. Choose the Database, the Data source, Trigger on (an entry created or changed, a new entry, a changed entry only) and Check every (minutes).

• It is armed at publication, starting from “now”: publishing never replays the database’s history.
• The interval defaults to 15 minutes, accepts 5 to 1,440, and never goes below the instance floor (INTEGRATION_POLL_MIN_MINUTES, 5 by default — see environment variables).
• Each check reads at most one page of entries; each entry becomes one run. The deduplication key is derived from the entry and its last edit time, so a repeated check creates no duplicate.
• A permanent failure (revoked token, database no longer shared) raises one notification, “The trigger of workflow … is broken”, until checks work again.

This is the recommended path: it works for every workspace without configuration.

Webhooks: Notion — event

Notion — event (trigger.notion) receives Notion’s webhooks on the workflow’s URL:

<PUBLIC_BASE_URL>/hooks/wf/<token>

• Getting the URL. The token is generated at the workflow’s first publication and returned only once. You can generate a new one with POST /api/v1/workflows/{id}/webhook (see the API): the response gives webhook.url, to prefix with <PUBLIC_BASE_URL>. A new URL invalidates the previous one.
• Subscribing. Notion has no API to create a subscription. In the Notion developer portal, open your integration’s Webhooks tab, create a subscription with the URL (it must be public HTTPS), and choose the events.
• Verification token. At creation, Notion sends a one-time request containing a verification_token, then waits for you to paste it back in the portal (Verify). Paste the same value in the connection’s Webhook verification token field: it becomes the signing key.
• Signature. Each event carries X-Notion-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body keyed with the verification token. Mankomail checks it before creating anything. A missing or wrong signature, or a connection with no verification token, gets the same 404 as an unknown URL; the reason is only written to the server logs.
• Filtering. Notion sends every event of the workspace to the same URL. Mankomail reads type in the body and creates a run only for the Events ticked on the trigger (default: Page properties updated); nothing ticked means everything. Ignored events are acknowledged with 202. Database concerned is informational: to handle one database only, compare data.notion.entity.id in a condition.
• Deduplication. Notion retries a delivery up to eight times with the same event id; Mankomail uses it as the deduplication key, so a replay creates no second run.
• Payload. The body is light: ids and metadata (data.notion.type, data.notion.entity.id, data.notion.authors), never the content. Read the page back with the Notion node if needed.
• Loops. A workflow that writes into Notion triggers new events. Compare {{ data.notion.authors[0].id }} with the connection’s bot id (User → Read the connection account) in a condition.

WARNING

The verification request Notion sends at creation is not signed. Because Mankomail rejects unsigned requests on this trigger, that request is answered 404 and its token is not shown in Mankomail. Obtain the verification_token by other means before pasting it in the connection, or use Notion entry changed, which needs no subscription.

Common errors

Message or code	Cause	What to do
Test: “the service answered something other than what we expected” (integration.unexpected_response)	The token is valid but nothing is shared with the integration.	In Notion, ··· → Connections → Add connections on a root page or database, then test again.
Test: “the service rejects the key” (integration.unauthorized)	Token revoked, regenerated, or mistyped.	Copy the current token from the integration’s settings and replace it.
Test passes without a workspace name	The User information capability is off.	Optional: turn it on to see the name and to list members.
Empty lists in the editor	Nothing shared, or the page was shared a moment ago (search is indexed).	Share the page; paste its URL or id in the meantime.
integration.not_found (Notion code object_not_found)	The page or database is not shared with the integration, or a database id was given where a data source id is expected.	Share the page; pick the database then the Data source in the editor.
integration.unauthorized during a run	401, or 403 for a missing capability (for example Insert comments for Create a comment).	Turn on the capability in Notion, or replace the token.
integration.rejected	400 or 422: Notion refused the body (unknown property, wrong value for the property type, validation_error).	Check property names and types against the data source schema.
integration.rate_limited	429 after retries. Mankomail sends at most 180 requests per minute per connection and retries up to 4 times, honouring Retry-After.	Transient: the engine resumes the step later.
integration.unavailable	5xx, 409 (concurrent write) or network failure, after retries.	Transient: the engine resumes the step later.
integration.connection_unusable	The connection was deleted, is not active, is out of your scope, or belongs to another service.	Pick a valid connection in the node.
Member picker fails	The token is a PAT, or User information is off.	Use the id mode of the picker, or an integration token with that capability.
Webhook events never start the workflow	Workflow not published, verification token missing or wrong in the connection, events not ticked, or the subscription points to an old URL.	Publish, paste the verification token, review Events, and check the subscription URL.

Webhook events

The events offered by the trigger. An event the provider adds later is still accepted when no event is ticked.

Event	Label
page.created	Page created
page.properties_updated	Page properties updated
page.content_updated	Page content updated
page.moved	Page moved
page.deleted	Page moved to trash
page.undeleted	Page restored
data_source.content_updated	Database entries updated
data_source.schema_updated	Database schema updated
comment.created	Comment created
comment.updated	Comment updated
comment.deleted	Comment deleted

Nodes that use this connection

• Notion — event — trigger.notion
• Notion entry changed — trigger.notion_changes
• Notion — notion.api