Skip to main content
OwnDocs

Notion Integration

3 min readStableBeginner

Connect a Notion database and every vote from the "Was this helpful?" widget lands in it as a row: the page path, a thumbs up or down, and the time it came in. You read feedback right in Notion, filter it, share it with your team. A free Notion plan is enough.

Why an integration at all? By default, votes are written to a JSONL file on your server. That works on any normal Node host. It doesn't work on Vercel, where the filesystem is read-only — the write fails and your reader sees an error. Notion is the fix for those hosts.

The setup needs two values:

NOTION_API_KEYstringrequired

The internal integration token from Notion. It starts with ntn_.

NOTION_DATABASE_IDstringrequired

The database that receives the votes. A 32-character ID, copied from the database URL.

Pick one of two ways to get them.

Option 1: Click through Notion

No terminal needed. About five minutes.

  1. Create the integration

    Open notion.so/profile/integrations and choose New integration. Name it something like docs-feedback, pick your workspace, and save. Copy the Internal Integration Secret — it starts with ntn_. That token is your NOTION_API_KEY. If that link ever moves, Notion's developer portal at notion.so/developers/tokens is the fallback from their official quick-start guide.

  2. Create the database

    Add a new page in Notion and choose Table. Name it Docs Feedback (any name works). Then give it exactly these three properties:

    Pathtitlerequired

    The page's URL path, like /integrations/notion. Notion adds a title property for you — rename it to Path if it says something else.

    Helpfulcheckboxrequired

    Checked for a thumbs up, empty for a thumbs down.

    Submitteddaterequired

    When the vote came in.

    Match the names exactly, capital first letter included. OwnDocs looks them up by name.

  3. Share the database with the integration

    Open the database, click the ⋯ menu at the top right, choose Connections, and pick the integration from step 1. This screen has no direct URL of its own — the Connections menu lives on each page and database, two clicks from the database you just made. Until you do this, the token sees nothing. Notion keeps bots out of your content by default.

  4. Copy the database ID

    Open the database as a full page and look at the URL. The 32 characters between the last dash and the ?v= part are the ID — highlighted here:

    Plain Text
    Plain Text
    https://www.notion.so/myworkspace/Docs-Feedback-218fb8926f02e83e52a542a8869bb279?v=594fa6dddfef38df9e92acffe2f1f1e1

    That's your NOTION_DATABASE_ID.

Option 2: One API call

Faster if you live in a terminal. One catch first: a bot can only create a database inside a page that's already shared with it. So share any page with your integration (step 3 above), then run one command.

Export your token and the parent page's ID — the 32 characters at the end of its URL:

Terminal
Bash
export NOTION_API_KEY="ntn_your-token"
export PARENT_PAGE_ID="ec55e31f5861e743bbd21fbff15d80f6"

Now create the database with the exact schema OwnDocs expects:

Create the database
Bash
curl -X POST https://api.notion.com/v1/databases \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -d '{
    "parent": { "type": "page_id", "page_id": "'"$PARENT_PAGE_ID"'" },
    "title": [{ "type": "text", "text": { "content": "Docs Feedback" } }],
    "initial_data_source": {
      "properties": {
        "Path": { "title": {} },
        "Helpful": { "checkbox": {} },
        "Submitted": { "date": {} }
      }
    }
  }'

The id in the response is your NOTION_DATABASE_ID:

JSON
JSON
{ "object": "database", "id": "218fb892-6f02-e83e-52a5-42a8869bb279" }

ℹ️ NOTE Skip the sharing step and Notion answers with a validation_error about parent.page_id. Bots can't create anything at the workspace root. Share the page, run the same command again, and it goes through.

Wire it into OwnDocs

For local development, put both values in .env.local:

.env.local
Bash
NOTION_API_KEY="ntn_your-token"
NOTION_DATABASE_ID="218fb8926f02e83e52a542a8869bb279"

For Vercel, add the same two under Project → Settings → Environment Variables, then redeploy.

Now open any page and vote. A row lands in the database within a second or two.

Related pages

Deployment

Was this page helpful?