---
title: "How to set up and configure Notion"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_and_configure_notion-icon.png
date: 2024-05-21T00:00:00.000Z
tag: Guides
description: "This guide describes how to register a public Notion application (a.k.a. ‘integration') and configure it so that you can use the Unified API to query pages and..."
url: "https://docs.unified.to/guides/how_to_set_up_and_configure_notion"
---

# How to set up and configure Notion
------
_May 21, 2024_

This guide describes how to register a public Notion application (a.k.a. ‘integration') and configure it so that you can use the Unified API to query pages and databases.


## Understanding Notion integrations: Internal vs Public


Before setting up your Notion integration, it's important to understand the two types of integrations Notion offers:

1. **Internal Integrations**: These are confined to a single workspace and are only accessible by members of that workspace. They're ideal for custom workspace enhancements.
2. **Public Integrations**: These are designed for a wider audience and can be used across any Notion workspace. They follow the OAuth 2.0 protocol for workspace access.

The main difference in terms of accessing user data is:

- For Internal Integrations, workspace members explicitly grant access to their pages or databases via Notion's UI.
- For Public Integrations, users authorize access to their pages during the OAuth flow, or by sharing pages directly with the integration.

For more information on the differences, refer to the [Notion API Overview](https://developers.notion.com/docs/getting-started).


## Setting up your Notion integration


The following steps outline how to register a public Notion integration:

1. Go to [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)
2. Click on your integration (or create a new one)
3. Follow the steps to register a new Notion integration.
    1. Under **Type**, select **Public**.
    2. Under **Redirect URIs**, enter `https://api.unified.to/oauth/code`
4. Click **Save**.
5. Go to the configuration settings of your newly created integration and make a note of the **OAuth Client ID** and **OAuth Client Secret.**
6. Still under the configuration settings, make sure to select the permissions you need for your app under **Capabilities** e.g. read or update content.
7. Enter your OAuth credentials on [https://app.unified.to/integrations/notion](https://app.unified.to/integrations/notion) to activate the Notion integration.

**Note:** If you wish to create an Internal integration, most of the steps above can be skipped, and you will need to enter your `Internal integration token` on [app.unified.to](https://app.unified.to/) instead. Instructions on how to find your internal token can be found [here](https://www.notion.so/help/create-integrations-with-the-notion-api).


## Querying databases in Notion


To query databases in Notion, you'll need to use our Unified KMS endpoint:

1. First, make sure you have a `connection_id` for your Notion integration.
2. Since database entries in Notion are technically pages, we'll use the **List all pages** endpoint:

    ```plain text
    GET /kms/{connection_id}/page
    ```


API reference: [List all pages](https://docs.unified.to/kms/page/List_all_pages)

1. When querying pages in a database, you need to pass the database ID as the `space_id` parameter. For example:

    ```plain text
    GET /kms/{connection_id}/page?space_id={database_id}
    ```

2. You can use additional parameters to filter and sort your results:
    - `limit`: Number of results to return (default: 30)
    - `offset`: Number of results to skip (default: 0)
    - `updated_gte`: Return only results updated on or after this date
    - `sort`: Sort by 'name', 'updated_at', or 'created_at'
    - `order`: Sort order ('asc' or 'desc')
    - `query`: Search query string
    - `fields`: Comma-separated list of fields to return

For example, to get the first 50 pages in a database, sorted by name in ascending order:


```plain text
GET /kms/{connection_id}/page?space_id={database_id}&limit=50&sort=name&order=asc
```


## Webhooks


Notion doesn't offer programmatic creation of webhooks, so you need to first create webhooks for your application.  Then, you can use our CreateWebhook API endpoint to select what data and connection you want to receive.

1. Go you your Notion's integrations page at [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations)
2. Either create a new integration or select an existing one.
3. Navigate to the **Webhooks** tab and click **+ Create a subscription**.

    ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_and_configure_notion-0.png)

4. Enter your public **Webhook URL** — this is the public endpoint where you want Notion to send events. It must be a secure (SSL) and publicly available endpoint. Endpoints in localhost are not
reachable.
    1. US: `https://api.unified.to/webhook/workspace/notion?workspace_id=$WORKSPACE_ID`
    2. EU: `https://api-eu.unified.to/webhook/workspace/notion?workspace_id=$WORKSPACE_ID`

    ![1ef497d7b9b3622de379e6907cd722167766413693ac9f1885b59eb028b4e7dd-webhooks-2.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_and_configure_notion-1.png)

5. Select the events that you are interested in receiving from all of your customers.  Created and Deleted events are associated with our `created` and `deleted` events, while all other events are associated with our `updated` event.  Both Notion's `Page` and `Database` are mapped to Unified's `KMSPage`, while `Comments` are mapped to `KMSComment`. You can modify these later if needed.
6. Click **Create subscription**.

    ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_and_configure_notion-2.png)

7. After you create the notion webhook, notion will send us a verification token. You can find that verification token in [https://app.unified.to/settings/api](https://app.unified.to/settings/api). Paste the `verification_token` value into the Verify Subscription form in Notion, and click **Verify subscription.**

    ![image.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_and_configure_notion-3.png)


Once completed, you can create webhooks in Unified.to that will receive these Notion events in real-time.