Notion Sensor

What it ingests

Page activity from Notion — wiki pages, database items, and their comments — optionally scoped to specific parent pages or databases. Notion is the document counterpart to Confluence for orgs whose knowledge base lives in Notion rather than Atlassian.

The integration only sees pages it has been invited to. That sharing model is the permission boundary; you do not grant workspace-wide read by storing a token.

Credential

References a notion_token credential by id. v1 is an internal integration secret (ntn_…, or the legacy secret_… prefix). Notion is a single cloud API, so there is no site URL beside the token.

curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin>" -H "Content-Type: application/json" \
  -d '{"type":"notion_token","name":"acme-notion","secret":"ntn_..."}'

OAuth (a public Notion integration that users install) is out of v1.

Config fields

Key	Required	Notes
parent_ids	no	Comma-separated Notion page or database IDs. Blank ingests every page the integration can already read. Paste IDs or Notion URLs — the 32-character id is extracted either way. Nested pages under a listed parent are included.

Provider-side setup

1. Open www.notion.so/my-integrations and create an internal integration.
2. Copy the Internal Integration Secret (ntn_…).
3. On each page or database you want ingested, open ••• → Connections (or Add connections) and invite the integration. Capabilities needed: Read content, Read comments, Read user information (including email addresses when Notion shares them).

A token with no invited pages authenticates but yields an empty poll — that is Notion refusing access, not a Corveil misconfiguration.

Wire-up

POST /api/sensors

{
  "sensor_type": "notion",
  "name": "Acme Notion",
  "config": {
    "parent_ids": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  },
  "credentials": { "api_token": "<notion_token credential id>" }
}

Leave parent_ids empty to ingest every page the integration has been invited to.

Verify

Run Test connection to confirm the token authenticates (GET /v1/users/me). Once polling, created and updated pages appear as document events, and their comments as conversation events.

Notes

Entity naming. Notion titles are unique only within a database, so database items are named Database/Title (e.g. Engineering/Onboarding). Wiki pages with no database parent use the bare title.

Occurred-at semantics. A page event is stamped with last_edited_time, recorded as an ingest-fallback occurred-at (eligible for title-date inference) rather than a true source event time — a page titled 2026-08-12 Architecture Review edited months later should anchor on its subject, not the edit. Comments are stamped metadata: a comment's timestamp really is when it was written.

First poll. A new source seeds its watermark to "now" and emits nothing on the first tick, so adding a source does not drag in the entire workspace. Use backfill to ingest history.

Burst drain. Notion search has no server-side last_edited_time filter, so a poll that hits the page budget persists a continuation cursor and resumes on the next tick rather than skipping the middle of a burst.