Notion URL shortener integration: OAuth + 2-way database sync

The Notion URL shortener integration went from Beta to Live on 4 June 2026. If you use Notion as a campaign hub, Elido reads the URLs in any database you pick, mints branded short links on your domain, writes them back to the table, and watches for destination edits. One OAuth click, no pasted secrets, field map configurable per database.

This article covers the OAuth connect step and scopes, the six-column structure, and the 2-way edit flow with conflict resolution. If you read the earlier Notion short links walkthrough, this is the deeper cut.

One-click OAuth: what actually happens when you press Connect#

Old token-paste flows asked you to generate a Notion internal integration token, paste it, then share each database with the integration by hand. That is gone. The new flow is three clicks: Connect in Elido, pick workspace + databases in Notion's consent screen, done. The OAuth dance follows the standard in the Notion API authentication docs, with PKCE on the auth code exchange.

The scopes you grant are narrow on purpose:

• read_content - read the Destination, Tags, and Title properties on the databases you picked.
• insert_content - create new rows when you ask Elido to mint a link from an external source (a Zap, a webhook, a CSV).
• update_content - write back the Short URL, Clicks, QR, and Last Synced properties.

Elido never asks for workspace-wide read or for pages you did not tick. Notion enforces this server-side too: a query against a database outside the grant returns a 403. The Notion API reference for database operations covers the verbs the integration uses.

When you complete consent, your browser hits api.elido.app/v1/oauth/notion/callback with the auth code. api-core exchanges the code for an access token, encrypts the token with the workspace KMS key (per ADR-0036), and stores it in integration_credentials. The plaintext token never touches disk or logs. A row also lands in the audit log so an admin can see who connected which Notion workspace, and when.

The connect button lives in the per-workspace Integrations tab, same as every other vendor in the integrations catalog. The Notion integration page has a screenshot of the consent screen. Permissions are revocable from Notion's Settings, Connections panel - revoking there fires a webhook that wipes the Elido-side token within 60 seconds.

Two modes: attach or create#

In attach mode, you point Elido at an existing database with a URL property. Elido adds the columns it needs (and only those), without renaming anything. In create mode, Elido provisions a fresh "Elido Links" database inside the page you pick. Most teams pick attach because their campaign table already exists with quarters of history. Either way, the schema below is identical.

Field mapping: the six columns and why they look like that#

Here is the column layout the integration uses. The names are defaults, you can rename them per database in Settings, Notion, Field map.

Column	Notion type	Direction	Notes
Short URL	URL	Elido writes	Read-only from the user's side; editing it does nothing.
Destination	URL	Notion writes	The target the short link points at. Editable.
Tags	Multi-select	Two-way	Tags are merged with set-union on conflict.
Clicks	Number	Elido writes	Polled every 5 minutes. Read-only.
QR	Files	Elido writes	A 1024px PNG of the QR for the short URL.
Last Synced	Date	Elido writes	UTC timestamp of the most recent sync touch.

A couple of choices worth calling out.

Clicks is intentionally not live. Notion has no streaming primitive, and hammering their endpoint per click would burn rate limit. Five minutes matches the freshness most ops teams need. For real-time, fire a webhook on link click events and forward to your own dashboard. Notion is the campaign view; the webhook is the firehose.

QR is a Files property, not a URL. Notion does not render external image URLs in tables, but it does render attached files as thumbnails. Elido uploads the PNG on first sync and re-uploads only if the short URL changes. See the QR codes feature page and the GS1 QR guide.

Tags is two-way with set-union. Only column where both sides write. Tag a row "launch-2026" in Notion, Elido has "winter-promo" from a Zap, next sync both tags exist on both sides. Removals propagate. The audit log records every change.

For UTM parameters, the UTM templates guide attaches a template to a folder so every link inherits the right utm_source. The Destination column stays clean, and Elido appends parameters at click-resolution time via smart link rules.

The 2-way edit flow: who wins when Notion and Elido disagree#

This is the part teams care about most, because sync tools have a history of silent overwrites. Here is the contract.

A worker inside api-core polls each connected database every five minutes for changes since the last last_edited_time watermark. On a property change it loads the field map and decides ownership. The rules are fixed:

• Notion owns: Destination, Tags (write side), Title.
• Elido owns: Short URL, Clicks, QR, Last Synced.
• Shared: Tags (read side, both sides see the merged set).

If a Notion-owned field changed in Notion, Elido updates internal state and emits an integration.notion.sync event. If an Elido-owned field changed (a click count tick), Elido writes back on the next sync.

The interesting case is a collision. Suppose you change Destination in Notion at 14:02:10 and a Zap writes a new Destination to Elido at 14:02:30, same five-minute window. Notion owns Destination, so Notion wins. Elido drops the Zap's write, posts a comment on the row ("Destination conflict at 14:02:30, kept Notion value, see audit log"), and emits a conflict event subscribable via webhooks. The Zap listens, decides whether to retry or alert.

No silent overwrites anywhere. Every write is logged. Every conflict gets a row comment. For a permanent record, pipe the audit stream into your warehouse via the ClickHouse export guide or hit the GraphQL API directly.

When the destination change should NOT propagate#

Sometimes you edit a Destination as a draft. Two patterns help.

Status property as a guard. Add a Select called "Sync" with Draft, Live, Paused. The integration only syncs rows where Sync = Live. Stage in Draft, flip to Live, next tick picks it up. Most marketing teams end up using this.

Pause the whole database. Settings, Notion, pause per database. Useful during a migration or bulk edits.

Setup walkthrough: from zero to first synced row in 4 minutes#

1. Connect Notion. Workspace settings, Integrations, Notion, Connect. Pick workspace, tick databases, Allow.
2. Pick a database. Settings, Notion, "Add database." Dropdown lists every database you granted. Pick one.
3. Map fields. Confirm Destination, Title, and the rest. Missing properties? Elido offers to create them.
4. Pick a domain. Choose a branded domain for the short links. No custom domain yet? Pick the default; migration is one click later.
5. Save and backfill. Elido reads every row, generates a short link for any with a Destination but no Short URL, writes back. Existing Short URLs are left alone.

Wall-clock time is around 4 minutes for 200 rows. Larger backfills hit Notion's three-requests-per-second cap on free workspaces. A 5,000-row database backfills in about 30 minutes; the worker batches and resumes on its own if rate-limited.

When to use this vs Zapier vs the API directly#

Three paths exist, not mutually exclusive.

The native integration is the right default if Notion is where the work happens. OAuth, conflict resolution, audit log, field map, no code.

A Zap is right for multi-step workflows ("when a row is added AND a Slack reaction lands, then create a link"). For one-to-one row-to-link mapping, the native integration is faster and cheaper. See the Zapier automation post.

The REST API is right if you are building a custom workflow on top of Elido. For developers building product integrations, the source under services/api-core/internal/integrations/notion/ is small enough to read in one sitting.

Comparing to Bitly or Rebrandly: neither has a native Notion integration as of writing. Both require Zapier or a custom script. See the vs Bitly page for the delta and the pricing page for which plans include unlimited Notion databases.

Troubleshooting: the four issues that hit us in Beta#

During the eight-week Beta, four classes of issue showed up. All are now handled in code, but it helps to know what to look for.

"Database not found" after a workspace rename. If a Notion admin renames the workspace, the workspace ID stays stable but cached metadata goes stale on our side for up to an hour. Workaround: hit "Force re-sync" in Settings, Notion. The cache TTL is set to 15 minutes in production, so this is mostly a Beta artefact.

Rate-limit during a large backfill. Notion's per-integration limit is three requests per second. A 5,000-row database hits this hard during the initial backfill. The worker exponentially backs off (250ms, 500ms, 1s, 2s, capped at 8s) and resumes. You will see "Throttled by Notion, resuming" in the activity log; this is normal.

Property type mismatch. The most common Beta bug. A user picked a Notion column of type "Text" for Destination instead of "URL." The field map validator now flags this at save time and refuses to proceed. If you see "Destination must be a URL property," change the column type in Notion first.

Multi-workspace user with shared databases. If the same human is a member of two Notion workspaces and both want to connect Elido, each workspace needs its own OAuth grant. The token is per-workspace, not per-user. The connect flow handles this correctly; just expect to click Connect twice.

For anything not on this list, the contact page goes to the integrations team directly. We see issues faster there than in generic support.

What lands next#

Two follow-ups on the roadmap. A "Notion form to short link" recipe so a form submission mints a tracked link. And two-way sync on a Workspace property so a link can follow when you move a row between databases. Both on track for Q3; we will note them in the changelog.

To measure the impact, the short link analytics primer covers which metrics actually matter and how to set up the Notion dashboard rows so they answer the right questions.