# Notion

Index and search Notion pages and databases in Risotto

Connect your Notion workspace to Risotto to make all your pages and databases searchable through the AI assistant.

> **Note:** Notion uses API token authentication rather than OAuth. You create an internal
> integration in Notion and provide the API secret key to Risotto. You must have
> Workspace Owner permissions in Notion to create integrations.

## Prerequisites

Before connecting Notion, ensure:

1. **Notion Account** - You have a Notion account with workspace access
2. **Workspace Owner Role** - You have Workspace Owner permissions to create integrations
3. **Risotto Admin Access** - You are an administrator in your Risotto organization

> **Tip:** You can bulk-share pages during integration creation using the "Access" tab in
> the Notion integration settings to save time on configuration.

## Initial Setup

1. **Open the Notion integration page**

   In your Risotto dashboard, go to [**Settings** > **Integrations** > **Notion**](https://dashboard.tryrisotto.com/settings/integrations/notion). On the **Knowledge** tab, click **Share pages**. If you have no index yet, click **Share pages** on the **Pages** row instead. The **Share pages** dialog opens.

2. **Create Notion Internal Integration**

   Visit the [Notion integrations page](https://www.notion.so/profile/integrations) and create a new internal integration:

   > **Tip:** Integrations are managed at that URL, not under your workspace's **Settings →
   > Connections** page (which only lists connections already added). The secret
   > you create belongs to the integration, not to your personal account, so it
   > keeps working when you leave the workspace or change roles.

   1. Click **New integration**
   2. Enter a descriptive name (e.g., "Risotto Knowledge Integration")
   3. Select your workspace
   4. Under "Capabilities," ensure **Read content** is enabled
   5. (Optional) Use the **Access** tab to pre-share pages with the integration
   6. Click **Submit** to create the integration
   7. Copy the **Internal Integration Secret** (API key)

   > **Info:** Keep your API secret key secure. You'll only see it once during creation, but
   > you can regenerate it later if needed.

   For detailed instructions, see [Notion's integration creation guide](https://developers.notion.com/guides/get-started/create-a-notion-integration#getting-started).

3. **Configure Index in Risotto**

   Return to the **Share pages** dialog and enter the fields:

   | Field                  | Required                                 | Description                                                                                                                                                                                                     |
   | ---------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Name**               | Yes                                      | Descriptive name (e.g., "Company Wiki"). Must be unique.                                                                                                                                                        |
   | **Integration secret** | Yes                                      | A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds the Internal Integration Secret from Notion. Choose it, or click **Add a vault credential** to create one. |
   | **Department**         | Org Admins and Managers: No. Others: Yes | Restrict access to a specific department                                                                                                                                                                        |
   | **Audience**           | No                                       | **Everyone** (the default) or **Assistant only**                                                                                                                                                                |

   > **Warning:** Only pages explicitly shared with your Notion integration will be indexed.
   > Pages must be shared via the integration's Access tab or through page-level
   > sharing.

   Click **Share pages** to start indexing.

   *Product example: The Share pages dialog on the Notion integration page: a name, the integration secret from the vault, Department and Audience, and Share pages.*

   **Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a Notion index too. It is the only place to set **Profile filters**.

## Monitoring Initial Indexing

After you share the pages, the index's card on the **Knowledge** tab reads **Indexing**, with the number of pages so far. On [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes), the **Indexing Jobs** panel above the table shows the same job while it runs:

- A progress bar captioned with the pages indexed so far and the pages found (for example, `Indexing Notion IT Help Center - 40/96 pages indexed`), and the percentage complete
- If the job fails, the caption shows the error, and a retry button appears next to the bar

When the job finishes, it leaves the panel, and the **Count** column of your Notion index shows the pages indexed.

> **Info:** Indexing speed depends on the number of pages. Expect approximately 5-10
> minutes for every 100 pages.

## Webhook Setup for Real-Time Updates

Webhooks keep your Notion content up-to-date automatically. When pages are edited or created, Risotto receives notifications and updates the index without manual reindexing.

1. **Start Webhook Configuration in Risotto**

   Navigate to [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes).

   Find your Notion index, click the three-dots menu, and select **Configure...**.

   In the **Notion webhook** section of the **Configure Index** dialog, click **Start webhook setup** to begin the verification process.

   *Product example: The Configure Index dialog for a Notion index, with Start webhook setup under Notion webhook.*

   Keep this dialog open - you'll need to copy values from it in the next step.

   You can also do this from the **Knowledge** tab of the Notion page: find the index's card and click **Turn on** on the **Live updates** row. The **Live updates** dialog holds the same **Notion webhook** section.

2. **Create Webhook Subscription in Notion**

   Open your [Notion integration settings](https://www.notion.so/profile/integrations) in a new browser tab.

   1. Select the integration you created earlier
   2. Navigate to the **Webhooks** section
   3. Click **Add webhook subscription**
   4. Copy the **callback URL** from the Risotto dialog
   5. Paste it into the **Endpoint URL** field in Notion
   6. Subscribe to the events `page.content_updated`, `page.created`, `page.deleted`, and `page.undeleted`
   7. Click **Submit** to create the subscription

   Risotto acts only on these four events. It accepts other events, such as `page.moved` and `page.properties_updated`, but ignores them. So a change to only a page's title or properties shows up after the next content edit of that page or a reindex. If you move pages into or out of an indexed page, reindex afterward.

   Notion will send a verification challenge to Risotto. The verification token should appear in Risotto within 1 minute.

   > **Warning:** If the verification token does not appear after 1-2 minutes, click **Resend
   > verification** in Notion's webhook settings. If the problem persists, you may
   > need to follow the steps below to delete the webhook, wait a few minutes, and
   > restart the process.

   For more details, see [Notion's webhook creation documentation](https://developers.notion.com/reference/webhooks#step-1-creating-a-webhook-subscription).

3. **Complete Verification**

   Once the verification token appears in Risotto:

   1. Copy the verification token from the Risotto dialog
   2. Return to the Notion webhook configuration page
   3. Paste the token into the **Verification token** field
   4. Click **Verify** in Notion
   5. Return to Risotto and click **Confirm webhook**

   > **Tip:** You have 30 minutes to complete the verification process. If the window
   > expires, you'll need to follow the steps to delete the webhook integration
   > below and restart the webhook setup.

   After verification completes, your webhook is active and Risotto will receive updates automatically.

   For more details, see [Notion's webhook verification documentation](https://developers.notion.com/reference/webhooks#step-2-verifying-the-subscription).

## How Content Updates with Webhooks

Once webhooks are configured, Risotto automatically keeps your index current:

- **Edited pages** are re-indexed about 10 to 15 minutes after the last edit
- **New pages in shared databases** are indexed automatically
- **Deleted pages** are removed from the index

> **Info:** Risotto waits for editing activity to stop before re-indexing to avoid
> indexing partial content while you're actively working on a page.

### Adding Individual Pages After Setup

Pages added to your workspace after initial setup require special handling:

- **Pages in shared databases**: Automatically indexed when created (no action needed)
- **Individual pages outside databases**: Must be manually shared with your integration

**Preferred: Add the page via Connections**

Grant access at the page level using **Connections** in the page settings menu
(⋯ **More** → **Connections** → add your integration). This is the simplest
approach for individual pages. For step-by-step instructions, see [Give your
integration page
permissions](https://developers.notion.com/guides/get-started/create-a-notion-integration#give-your-integration-page-permissions)
in Notion's developer guide.

**Alternative: Bulk sharing from integration settings**

If you are a workspace owner or need to share many new pages at once, you can
share from your integration instead:

1. Visit your [Notion integration settings](https://www.notion.so/profile/integrations)
2. Select your integration
3. Use the **Access** tab to share pages in bulk

> **Warning:** No matter how you share the page with your integration, you must edit and save
> the page to trigger a webhook event. Otherwise, Risotto won't know the page is
> available until the next manual reindex.

## Managing Your Webhook

### Deleting a Webhook

To remove webhook functionality:

1. Navigate to [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your Notion index
3. Click the three-dots menu and select **Configure...**
4. Click **Delete webhook**

Or click **Manage** on the **Live updates** row of the index's card on the Notion page's **Knowledge** tab.

> **Warning:** Deleting the webhook in Risotto does not automatically delete it in Notion.
> You should also delete the webhook subscription in your Notion integration
> settings to prevent unnecessary webhook calls.

To re-enable webhooks after deletion, follow the webhook setup steps again.

## Reindexing Content

Manual reindexing is useful when:

- Adding many new pages at once

- Troubleshooting indexing issues

- Refreshing all content to ensure accuracy

- Database rows changed only in their columns (see [Database rows](#database-rows))

You can reindex while a webhook is active. Risotto pauses webhook events during the rebuild and keeps the webhook.

When the index has a webhook, a reindex keeps the same index. Without a webhook, a reindex replaces the index with a new one that has a new ID. Runbook [knowledge directives](https://www.tryrisotto.com/docs/dashboard/runbooks#steering-knowledge-with-directives) that name the old index stop working, and the runbook editor shows them as "source no longer available". Add those directives again after the reindex, or set up the webhook first.

### How to Reindex

1. Go to [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your Notion index
3. Click the three-dots menu and select **Reindex**

Reindexing will:

- Fetch all currently shared pages and databases
- Update content that has changed
- Add new pages created since last index
- Remove pages that are no longer shared with the integration

### Page content

Risotto indexes the text of each page that is shared with the integration:

- Paragraphs, headings, bulleted and numbered lists, to-do items, toggles, callouts, quotes, and code blocks
- Tables, one line for each row
- Content inside toggles and columns
- Child pages, as separate pages

Risotto does not index uploaded files, PDFs, images, videos, audio, embeds, bookmarks, link previews, or equations. An uploaded HTML file is a file, so Risotto does not read its content. To make that content searchable, paste its text into the page.

### Database rows

Risotto indexes each database row as a page. A row's text is its page body, then one line for each column, in the form `<column name>: <value>`.

- **Rows with content only in columns.** A row with an empty body is indexed when at least one column other than the title has a value. A row with only a title is skipped.
- **Title.** Risotto reads the row's title from the database's title column, whatever its name.
- **Column types.** Risotto reads Title, Text, Number, Select, Multi-select, Date, Person, and URL columns. It ignores other types, such as Status, Checkbox, Email, Phone, Formula, Relation, and Rollup. An empty Person column adds no line.
- **Column edits.** The webhook does not re-index a row when only its columns change. Reindex the index to pick up column edits. Rows that Risotto skipped before September 30, 2026, because their content was only in columns, are indexed at the next reindex.

## Access Control

### Department Restriction

Restrict who can search the Notion index:

1. When creating or editing the index, select a **Department**
2. Only members of that department will see results from this index

### Organization-Wide Access

Select "Organization-wide (no department restriction)" to allow all users to search the Notion content.

> **Note:** Risotto's access control operates independently of Notion's page permissions.
> All users with access to the index can search all indexed pages, regardless of
> their Notion permissions.

## Troubleshooting

### Verification token not appearing in Risotto

**Cause**: The verification challenge from Notion was not received or timed out.

**Solutions**:

- Click **Resend verification** in Notion's webhook settings and wait 1-2 minutes
- If still not appearing, delete the webhook subscription in Notion, cancel the setup in Risotto, wait a few minutes, and restart the entire webhook setup process

### No pages are being indexed

**Cause**: Pages have not been shared with your Notion integration.

**Solutions**:

- Verify sharing in your [Notion integration settings](https://www.notion.so/profile/integrations) under the Access tab
- Share pages with your integration using the integration's Access tab or page-level sharing
- Wait for indexing to complete and check the page count

### Newly added pages aren't being indexed

**Cause**: The webhook event was not triggered for the new page.

**Solutions**:

- Verify the page is shared with your integration
- Edit and save the page to trigger a webhook event
- Wait approximately 15 minutes for the webhook to process
- If the page is in a database, ensure the parent database is shared with the integration

### Authentication failed or Invalid API key

**Cause**: The API secret key is incorrect or has been regenerated.

**Solutions**:

- Verify your integration still exists in [Notion's integration settings](https://www.notion.so/profile/integrations)
- If you regenerated the API secret, get the new secret key from Notion
- Put the new secret in the vault credential that the index uses: in **Settings → Credential Vault**, open the credential's row menu and choose **Rotate Value** (see [Rotate a value](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault#rotate-a-value)). The index's **Configure** dialog does not hold the secret.

### Webhook stopped working after initial setup

**Cause**: The webhook subscription was deleted or expired, or the API key was regenerated.

**Solutions**:

- Check your [Notion integration webhooks](https://www.notion.so/profile/integrations) to verify the subscription still exists
- If missing, recreate the webhook using the webhook setup steps
- If you regenerated the API secret, rotate the value of the index's vault credential (see [Rotate a value](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault#rotate-a-value))

## Permissions Explained

When you create a Notion internal integration, you grant these permissions:

| Permission              | Description                                                                      |
| ----------------------- | -------------------------------------------------------------------------------- |
| **Read content**        | Read pages, databases, and blocks that are shared with the integration           |
| **Read comments**       | Read page comments (optional capability)                                         |
| **No user information** | Internal integrations cannot access personal information about workspace members |

> **Info:** Internal integrations use workspace-level permissions and can only access
> content explicitly shared with them. They cannot access all workspace content
> automatically.

Risotto's Notion integration is read-only and never modifies your pages or databases.

## Security Considerations

### API Key Storage

- API secret keys are encrypted at rest
- Keys are never exposed in logs or UI after initial entry
- Credentials are isolated per organization

### Data Access

- Risotto only reads content - no write access to Notion
- Indexed content is stored securely within your Risotto instance
- Access respects your configured department restrictions
- Only content shared with your integration is accessible

### Webhook Security

- Each webhook uses a unique callback URL
- The callback URL expires after 30 minutes if token verification is not
  completed and then stops receiving events
- Webhook subscriptions are verified using Notion's verification flow
- Verification tokens validate that requests come from Notion
- Invalid webhook requests are rejected and logged

## Next Steps

After setting up your Notion index:

1. **Test the integration** using [**Knowledge** > **Playground**](https://dashboard.tryrisotto.com/knowledge/playground)
2. **Ask Risotto questions** about your indexed content in Slack
3. **Monitor answer quality** in the Analytics dashboard
4. **Configure webhook subscriptions** for automatic updates
5. **Adjust access control rules** to match your organizational structure

For additional help, contact support at <support@tryrisotto.com>.

Source: https://www.tryrisotto.com/docs/integrations/knowledge/notion
