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.
Prerequisites
Before connecting Notion, ensure:
- Notion Account - You have a Notion account with workspace access
- Workspace Owner Role - You have Workspace Owner permissions to create integrations
- Risotto Admin Access - You are an administrator in your Risotto organization
Initial Setup
Open the Notion integration page
In your Risotto dashboard, go to 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.
Create Notion Internal Integration
Visit the Notion integrations page and create a new internal integration:
- Click New integration
- Enter a descriptive name (e.g., "Risotto Knowledge Integration")
- Select your workspace
- Under "Capabilities," ensure Read content is enabled
- (Optional) Use the Access tab to pre-share pages with the integration
- Click Submit to create the integration
- Copy the Internal Integration Secret (API key)
For detailed instructions, see Notion's integration creation guide.
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 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 Click Share pages to start indexing.
Create index on Knowledge > Indexes 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, 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.
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.
Start Webhook Configuration in Risotto
Navigate to 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.
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.
Create Webhook Subscription in Notion
Open your Notion integration settings in a new browser tab.
- Select the integration you created earlier
- Navigate to the Webhooks section
- Click Add webhook subscription
- Copy the callback URL from the Risotto dialog
- Paste it into the Endpoint URL field in Notion
- Subscribe to the events
page.content_updated,page.created,page.deleted, andpage.undeleted - Click Submit to create the subscription
Risotto acts only on these four events. It accepts other events, such as
page.movedandpage.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.
For more details, see Notion's webhook creation documentation.
Complete Verification
Once the verification token appears in Risotto:
- Copy the verification token from the Risotto dialog
- Return to the Notion webhook configuration page
- Paste the token into the Verification token field
- Click Verify in Notion
- Return to Risotto and click Confirm webhook
After verification completes, your webhook is active and Risotto will receive updates automatically.
For more details, see Notion's webhook verification documentation.
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
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 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:
- Visit your Notion integration settings
- Select your integration
- Use the Access tab to share pages in bulk
Managing Your Webhook
Deleting a Webhook
To remove webhook functionality:
- Navigate to Knowledge > Indexes
- Find your Notion index
- Click the three-dots menu and select Configure...
- Click Delete webhook
Or click Manage on the Live updates row of the index's card on the Notion page's Knowledge tab.
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)
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 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
- Go to Knowledge > Indexes
- Find your Notion index
- 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:
- When creating or editing the index, select a Department
- 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.
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 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
- 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). 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 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)
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 |
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:
- Test the integration using Knowledge > Playground
- Ask Risotto questions about your indexed content in Slack
- Monitor answer quality in the Analytics dashboard
- Configure webhook subscriptions for automatic updates
- Adjust access control rules to match your organizational structure
For additional help, contact support at support@tryrisotto.com.
Something wrong or missing? Report an issue · View as Markdown