Notion
Start agents when pages are created or changed or comments are added in Notion, and post their results as comments or new pages.
On this page
| Modes | Inbound, outbound |
| YAML type | notion |
| Credentials | A Connection of type notion, with the secret of a Notion internal integration |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A matching event starts every linked agent. |
| While paused | Events get 200 and start no runs. Outbound sends nothing. |
Set up
Create an internal integration at notion.so/my-integrations and turn on the capabilities your connectors need. Copy the Internal Integration Secret from its Configuration tab. Then open each page or database the agents should see, choose Connections in the three-dot menu, and add the integration.
In connic, open Project Settings → Connections, click New connection, and choose Notion. You can also create the Connection from the Connection picker in the connector form. Enter a Name, paste the secret under Integration secret, and click Create connection. connic checks the secret with Notion and shows the Webhook URL.
For inbound connectors, open the integration's Webhooks tab in Notion, create a subscription with the webhook URL, and pick the events your connectors use. Back in connic, click Refresh in the Connection until the Verification token appears, copy it, and paste it under Verify in Notion.
Open the agent. In Connector Flow, click Add inbound connector for page and comment events or Add outbound connector for comments and pages. Then click Create New Connector and choose Notion.
Choose the mode, Inbound (Page and comment events) or Outbound (Comments and pages), and pick the Connection under Connection. For inbound, enter the Events. Optionally enter a Data source. Click Create. For outbound, then choose how the agent uses the connector and click Link connector.
Configuration
The fields of a Notion connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | notion. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Inbound and outbound. Name or ID of a Notion Connection. Every inbound connector on it receives the integration's events. Dashboard: Connection. |
| config | object | Required | Notion settings. |
| events | string[] | Required | Inbound. The events that start runs: page.created, page.properties_updated, and comment.created. Subscribe to the same events in Notion. Dashboard: Events, one per line, starting with page.created and comment.created. |
| data_source | string | Optional | Inbound and outbound. A link to a database or one of its data sources. A database with several data sources needs the link of one of them. Inbound connectors only receive events of its pages, and outbound connectors create pages there. Share the database with the integration. Dashboard: Data source. |
The integration secret belongs to the Connection, not to the connector. So does Accept a new verification token; see Notion subscription.
Generated values
connic sets these when you save the connector or its Connection, or when Notion sends the verification token.
| Value | Modes | Description |
|---|---|---|
| Webhook URL | Inbound | The Connection's URL for the subscription in Notion. One URL serves every connector on the Connection. |
| Verification token | Inbound | The token Notion sends to the webhook URL once you create the subscription. connic checks the signature of every event with it. |
| Bot user and workspace | Inbound, outbound | The integration's bot user and its workspace, stored on the Connection when you save it. |
| Data source | Inbound, outbound | The ID, name, and title property of the data source you enter by its link. |
Agent input
Modes: Inbound
Notion's events only name the page or comment, so connic reads it from Notion first. Then an inbound connector starts a run for every linked agent whose events and data source match. The run receives:
{
"event": "comment.created",
"page_id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"title": "Refund request: order 1042",
"url": "https://www.notion.so/acme/Refund-request-order-1042-1f2e3d4c5b6a47988a7b6c5d4e3f2a1b",
"data_source_id": "8c7b6a59-4e3d-4c2b-9a1f-0e9d8c7b6a59",
"properties": { "Status": { ... }, "Name": { ... } },
"text": "Can we approve this today?",
"authors": ["3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d"],
"conversation_id": "notion:1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"comment_id": "2a3b4c5d-6e7f-4089-9a1b-2c3d4e5f6a7b",
"discussion_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"raw": { ... }
}eventis the Notion event, such aspage.created.page_id,title,url, andpropertiesdescribe the page, also for comments.data_source_idis set for pages in a database.textis the page's content in Markdown for page events, and the comment's text forcomment.created, which also setscomment_idanddiscussion_id.conversation_idstays the same for every event of one page. To give the agent the earlier events as history, setsession.key: input.conversation_idin its YAML; the connector doesn't turn on sessions by itself.authorsare the IDs of the Notion users who caused the event, andrawis Notion's event as sent.
An event that Notion sends again doesn't start another run. Inbound mode doesn't reply by itself: to comment on the page, link the agent to an outbound Notion connector that uses the same Connection; see Outbound delivery.
Integration and capabilities
The integration only sees pages and databases shared with it. Comments and pages from your agents show the integration as their author, and events the integration causes are ignored, so agents don't trigger themselves on their own comments. Turn on the capabilities under Capabilities in the integration's Configuration tab:
| Capability | Needed for |
|---|---|
| Read content | Inbound. connic reads the page of every event. |
| Read comments | Inbound, for comment.created. |
| Insert comments | Outbound comments. |
| Insert content | Outbound pages in a data source. |
Notion subscription
Modes: Inbound
A webhook subscription belongs to the integration, so you create it once per Connection in Notion, and connic routes each event to the Connection's inbound connectors. After you create it, Notion sends a verification token to the webhook URL. connic stores it on the Connection, shows it there, and checks the signature of every event with it.
Once the first signed event has arrived, connic keeps the token and ignores new ones. Notion can't move a subscription to another URL, so for a new subscription turn on Accept a new verification token in the Connection first. The next token Notion sends replaces the stored one, and connic turns the setting off again. Saving the Connection with the secret of another integration also clears the token.
Outbound delivery
Modes: Outbound
An outbound Notion connector posts once each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides where:
- When the output or payload sets
page_id, as a page link or ID, it comments on that page. - When the run came in through a Notion inbound connector on the same Connection, it comments on the page the run started from. When a comment started the run, the reply goes into that comment's discussion.
- Otherwise it creates a page in the connector's data source. The title is
titlefrom the output or payload, or else the first line of the text, and the text becomes the page's content.
Automatic output
An automatic link posts the run's final output. Plain text becomes the text. A JSON object takes the text from body, text, message, response, or output, in that order, and can set title and page_id. New pages render the text as Markdown; comments show it as plain text.
{
"title": "Refund approved: order 1042",
"body": "The order shipped late, so the refund is approved.\n\n- Amount: 49 EUR\n- Method: original payment"
}Agent-tool and middleware payload
The model or middleware passes body, which is required and can't be empty, and optionally title and page_id. Other fields are rejected.
{
"body": "Approved. The refund goes out today.",
"page_id": "https://www.notion.so/acme/Refund-request-order-1042-1f2e3d4c5b6a47988a7b6c5d4e3f2a1b"
}Delivery and retries
When Notion rate-limits a comment or page, connic waits and sends it again. The connector's runs show each delivery with the comment or the page's link, or with the error.
Limits and errors
| Limit | Value |
|---|---|
| Delivery time | Notion usually sends an event within a minute, at the latest within 5 minutes. |
| Batched changes | Changes to a page's properties within about a minute arrive as one page.properties_updated event. |
| Order | Events can arrive in a different order than they happened. |
| At most once | Notion aims to send each event at most once, so an event can be missing. When connic doesn't accept a delivery, Notion tries again up to 8 times over about 24 hours. |
| API requests | Notion allows an integration 180 requests per minute, or 600 on its Business and Enterprise plans. Each event takes two requests, each comment or page one. When Notion rate-limits, connic waits and retries the delivery. |
| Comment length | 200,000 characters. |
| Page title | Without a title, the first line of the text, cut at 2,000 characters. |
Events with a missing or wrong signature get 401. When connic can't read an event's page or comment, the connector's runs show why; an event whose page wasn't shared with the integration starts nothing. Saving a Connection fails when Notion rejects the secret, and saving a connector fails when the integration can't see its data source. A delivery fails when Notion rejects it, for example when the integration lacks a capability.