Notion has become the default workspace tool for a large number of teams. Docs, project tracking, databases, internal wikis — it handles all of it reasonably well. Naturally, teams that have invested heavily in Notion want to connect it to everything else: their CRM, their forms, their project management tools, their billing system.
The Notion API makes many of these connections possible. But it has real limitations that are easy to underestimate, and the gap between "the API can do this" and "you should build this on the API" is significant for certain use cases.
This post covers what the API can and cannot do, the rate limit problem, five common integration patterns with cost breakdowns, and when Make beats custom code for Notion integrations.
What the Notion API Can Do
The Notion API covers the core operations you would expect from a database and content platform:
- Read pages and blocks. Retrieve any page your integration has access to, including its full block content — paragraphs, lists, tables, embedded databases, and child pages.
- Write pages and blocks. Create new pages within a database or workspace, update page properties, append blocks to existing pages.
- Query databases. Filter, sort, and paginate database entries using Notion's filter syntax. Returns up to 100 results per request.
- Update database properties. Change the value of any property on a database entry — select fields, multi-select, dates, people, URLs, numbers, checkboxes.
- Create pages from templates. Create a new page in a database with pre-filled property values by passing the properties as part of the create request.
- Manage users and comments. Retrieve workspace members (limited), create and retrieve comments on pages (limited API surface).
That is a solid foundation. For integration work, the read/write and query capabilities cover the majority of what teams actually need.
What the Notion API Cannot Do
The limitations are as important as the capabilities, and several of them are architectural — they will not be fixed by an API version update.
No native webhooks. Notion has no push notification system. There is no way to subscribe to changes and receive a callback when a database entry is updated or a page is created. Everything is polling. You query the API on a schedule, detect changes yourself, and react accordingly. For use cases requiring real-time response, this is a fundamental constraint.
No binary file uploads. You cannot upload a file to Notion via the API. File attachments in Notion must be added through the UI or via a direct URL reference to an externally hosted file. If your integration needs to attach a PDF, an image, or any binary file to a Notion page, you must first host that file somewhere (S3, a CDN, a file hosting service) and then attach the URL.
Formula fields are read-only. Notion's formula fields — which compute values based on other properties — cannot be written via the API. You can read the computed value, but you cannot set it. If your database relies on formulas to calculate a status, a score, or a date, those values update automatically based on underlying properties you can write, but you cannot push a formula value directly.
Full-text search limitations. The Notion search API searches page titles and top-level block content, but it is not a full-text index of all content inside all blocks. For search-heavy integrations — finding all pages that mention a specific client name, for example — the search API will miss content buried in nested blocks or tables.
No bulk write API. Every create and update operation is a single API call for a single page or property. There is no batch write endpoint. Syncing 500 records means 500 API calls, subject to the 3 requests-per-second rate limit.
The Rate Limit Problem
The 3 requests-per-second rate limit is the most practically important constraint for integration work. It sounds high until you run the math.
If you need to sync 1,000 database entries from an external system into Notion:
- Reading: 10 requests (100 results per query × 10 pages) = 4 seconds
- Writing: 1,000 requests at 3/second = 333 seconds (5.5 minutes) under ideal conditions
- With retries and backoff on rate limit errors: realistically 8-12 minutes
For a one-time migration, this is acceptable. For an ongoing sync that runs every 15 minutes, a 10-minute write operation means your integration is constantly running — and one network hiccup causes the entire next sync to queue behind the previous one.
The practical implication: Notion integrations that write large amounts of data need careful design. Incremental syncs (only writing changed records, not the full dataset), change detection with checksums, and write queuing with backoff are not optional — they are requirements for any integration handling more than a few hundred records.
5 Common Notion Integration Patterns
1. CRM sync: push contacts to a Notion database
Pull new or updated contacts from a CRM (Salesforce, HubSpot, Pipedrive) on a schedule and write them to a Notion database as structured entries. Useful for teams that want a Notion-native view of their pipeline without logging into the CRM.
The challenge: CRM contact records have dozens of fields; Notion database properties need to be configured to match. Field mapping and handling CRM field types (multi-select, relationships, custom objects) requires careful setup. One-way sync (CRM to Notion) is straightforward. Bidirectional sync — where updates in Notion flow back to the CRM — is significantly more complex because Notion has no webhooks, so you are polling for changes.
2. Project intake: form submission to Notion page
When a client or internal stakeholder submits a form (Typeform, Google Forms, a custom web form), create a new Notion page with the form responses prefilled as database properties. Attach the form submission timestamp, the submitter's email, and any categorization logic as structured properties.
This is one of the cleanest Notion integration use cases because the trigger is external (a form submission webhook) and the write is a single Notion API call. The event-driven model avoids the polling problem entirely.
3. Status board: pull GitHub or Jira data into Notion
A scheduled sync queries open issues or pull requests from GitHub or Jira and creates or updates corresponding Notion database entries with current status, assignee, and priority. Product managers and non-technical stakeholders get a Notion-native view of engineering work without Jira access.
The practical limitation here is freshness: with a 15-minute polling interval, the Notion view is always up to 15 minutes stale. For operational dashboards where people expect real-time data, this gap is noticeable. For weekly planning views, it is fine.
4. Invoice tracking: create Notion entries from Stripe payment events
When a Stripe payment succeeds or a subscription renews, create a Notion database entry with the payment amount, customer name, invoice ID, and payment date. Finance teams can review payment history in Notion without Stripe dashboard access.
Stripe has native webhooks, so this integration is event-driven on the Stripe side. The Notion write is triggered immediately on payment. This is a good fit for the Notion API because the write volume is low (one entry per payment event, not bulk operations) and the trigger is external.
5. Content calendar: auto-create Notion pages from a planning spreadsheet
A scheduled sync reads a Google Sheets editorial calendar and creates Notion pages for each planned piece of content — with the topic, target keyword, author assignment, and publish date as database properties. The content team works in Notion; the planning process stays in Sheets.
The unidirectional flow (Sheets to Notion, not back) avoids the sync conflict problem. New rows in Sheets become new Notion pages. Status updates happen in Notion. There is no attempt to reflect Notion status changes back to Sheets.
Polling vs Webhooks: The Practical Impact
Because Notion has no webhooks, every integration that reacts to changes in Notion must use scheduled polling. A script runs every 5-15 minutes, queries the database, compares results against a stored snapshot, and triggers downstream actions for any changes detected.
The implications for your architecture:
Events are delayed. A Notion database entry updated at 9:00am may not trigger downstream action until 9:14am if you poll every 15 minutes. For most business processes — updating a CRM, sending a notification, creating a task — this delay is fine. For anything time-sensitive, it is a problem.
You need to store state. Polling-based change detection requires a snapshot of the previous query result. You compare the current query against the snapshot to find changes. This state needs to live somewhere persistent — a database, a file, a key-value store. This is an infrastructure cost that webhook-based integrations do not have.
Missed changes during downtime. If your polling script is down for an hour, you miss all changes that happened during that window. Webhook-based integrations buffer events on the sender's side and replay them when the receiver comes back. Polling cannot recover missed events without a manual re-sync.
For many teams, these tradeoffs are acceptable. The key is going in with eyes open: Notion integrations are inherently near-real-time, not real-time, and they require more state management than webhook-based integrations.
Cost Breakdown by Integration Type
| Integration type | Make or Zapier | Custom script | Full custom integration |
|---|---|---|---|
| Simple form → Notion | $20–49/month | $500–1K setup | — |
| CRM sync (one-way) | $49–99/month | $1K–3K setup | — |
| Bidirectional sync | Not reliable | $3K–8K setup | $8K–20K |
| Real-time pipeline | Not possible | — | $15K–30K |
The "not reliable" designation for bidirectional sync via Make/Zapier is deliberate. Both tools offer Notion modules, but bidirectional sync requires detecting which side changed most recently and resolving conflicts — logic that no-code tools handle poorly. You end up with sync loops, duplicate entries, and overwrites. Custom code with explicit conflict resolution logic is the right architecture for bidirectional sync.
Make vs Zapier vs Custom Code for Notion
Make (formerly Integromat) handles Notion integrations significantly better than Zapier. The reasons:
Make's Notion module is more complete. Make exposes the full Notion API surface — database queries with filters, block-level operations, multi-select and relation property types. Zapier's Notion integration covers the basics but has gaps on complex property types and database query filters.
Make handles pagination natively. If a Notion database query returns more than 100 results, Make's iterator module automatically handles the cursor-based pagination. Zapier does not handle pagination gracefully for large datasets.
Make's pricing model fits polling better. Make charges per operation (scenario execution), not per task. A polling scenario that runs every 15 minutes and finds no changes costs very little. Zapier charges per task regardless of whether the task finds anything to do.
Where custom code beats both: when you need complex field mapping logic, multi-step conditional processing, bidirectional sync with conflict resolution, or integration with internal systems that are not in Make's or Zapier's connector library. Custom Python or Node.js code with the official Notion SDK handles all of these and is cheaper to run at scale than any SaaS automation tool.
The Anti-Pattern: Notion as a Production App Backend
Some teams reach a point where Notion is working so well as an internal tool that someone suggests using it as the database backend for a customer-facing app or internal portal. This is a mistake worth addressing directly.
The rate limit makes it too slow for concurrent users. Three requests per second, shared across all users of your app, means a modest surge — 10 users each triggering one query — backs up into a queue. Real databases handle thousands of concurrent operations; Notion handles three per second.
No transactions. If your app writes to three Notion database entries as part of one operation and the second write fails, there is no rollback. You have partial state. Real databases solve this with transactions. Notion has no equivalent.
No indexing beyond what Notion exposes. Complex queries — "give me all records where property A is X, property B is greater than Y, and the related record in another database has status Z" — either cannot be expressed in Notion's filter syntax or require multiple API calls with client-side join logic.
The right pattern is a real database as the system of record, with a Notion sync for visibility. A content team's publishing pipeline example: the canonical data lives in a Postgres database. A scheduled sync writes a Notion view of the data for editorial review. The Notion view is read-only — no one edits it directly — so there are no sync conflicts. Everyone gets the Notion interface they want, and the production app has a proper backend.
A Real Example
A content team at a B2B SaaS company used Notion as their editorial calendar — every article, social post, and newsletter issue was a Notion database entry with status, author, publish date, and target keyword properties. Their publishing platform was Webflow. Every week, someone manually created the Webflow draft and set the SEO fields based on the Notion entry. It took 15-20 minutes per piece.
A custom integration automated the handoff. When a Notion entry moved to "Ready to Publish" status, a polling script detected the change (running every 10 minutes), called the Webflow CMS API to create the draft with the correct title, slug, meta description, and author fields, updated the Notion entry with the Webflow draft URL, and sent a Slack notification to the editor. The manual step shrank from 15 minutes to a final review and "Publish" click.
What changed:
Before: 15–20 minutes per piece of content manually creating Webflow drafts
After: polling integration detects "Ready to Publish" in Notion, creates Webflow draft automatically
Saved: ~3 hours/week for a team publishing 10–12 pieces per week
Frequently Asked Questions
Does Notion have webhooks?
No. Notion has no native webhook system as of 2026. There is no way to receive a real-time push notification when a Notion page or database entry changes. All change detection requires scheduled polling: query the database on an interval, compare against a previous state snapshot, and trigger downstream actions when changes are detected. For most business workflows where a 5-15 minute delay is acceptable, polling works well. For use cases requiring genuine real-time response, Notion is not the right data source — or you need to add a separate event system on top of it.
What are the Notion API rate limits?
Three requests per second per integration token. This is the official rate limit. In practice, sustained operations at exactly 3 requests/second often trigger rate limiting due to measurement windows — plan for 2-2.5 requests/second in production to stay reliably under the limit. Notion returns a 429 response when rate limited with a Retry-After header. Any production integration must implement exponential backoff retry logic. Bulk write operations are the primary pain point: creating or updating 500 database entries one by one takes 3-4 minutes minimum. There is no batch write API to accelerate this.
Can I use Notion as a database for my app?
For internal tooling with light usage — a handful of team members checking a dashboard a few times per day — yes, Notion can serve as a data store. For any user-facing feature, any real-time requirement, or any operation involving concurrent users, no. The 3 requests/second rate limit creates a hard ceiling on throughput. There are no transactions, so concurrent writes can leave partial state. Complex query patterns require multiple API calls with client-side joins. Use a real database (Postgres, Supabase) as the system of record and sync a read-only view to Notion for visibility if needed.
Start with a Scoping Call
The right architecture for a Notion integration depends on what you are trying to connect, how much data you are moving, and how real-time the sync needs to be. Those three variables determine whether Make handles it in an afternoon or whether a custom integration is the right call.
