Choosing Between Notion Webhooks and Polling for Real‑Time Updates

Problem: Real‑Time Updates from Notion

When building an integration that reacts to changes in a Notion workspace, you need a reliable way to receive notifications as soon as a page or database is edited. Notion offers two primary mechanisms: webhooks and polling. Choosing the right one depends on your environment, latency requirements, and operational constraints.

Decision Guide: Webhooks vs Polling

Below is a quick decision matrix that summarizes the key constraints and trade‑offs for each approach. Use it to decide which path fits your use case.

Factor	Webhooks	Polling
Latency	Near real‑time (seconds)	Bound by interval (seconds to minutes)
Network Overhead	Low – only when events occur	High – repeated GETs even if nothing changed
Setup Complexity	Requires HTTPS endpoint, signature verification, public exposure	Simple – just a scheduled request
Rate Limits	None for event delivery (but endpoint must respond 2xx)	Must stay within 50 calls/min per integration
Reliability	Depends on endpoint stability; Notion retries on failure	Guaranteed delivery but may miss changes between polls
Security	Signature verification protects against tampering	Less exposure – no external calls from Notion
Scalability	Scales with event volume; Notion handles load	Scales with your polling frequency; higher load on your server

When to Prefer Webhooks

• You need sub‑minute notification latency.

When to Use Polling

Concrete Implementation: Node.js Example

Below are two minimal snippets that you can run locally or deploy to a public host like Heroku. They illustrate how to validate each approach.

1. Webhook Listener (Express)

// webhook-server.js
const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const NOTION_SECRET = process.env.NOTION_SECRET; // Integration secret

app.post('/notion-webhook', (req, res) => {
  const signature = req.headers['x-notion-signature'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', NOTION_SECRET)
    .update(body)
    .digest('hex');

  if (signature !== expected) {
    console.warn('⚠️  Signature mismatch');
    return res.sendStatus(400);
  }

  console.log('✅  Received event:', req.body);
  // Process event here
  res.sendStatus(200); // Acknowledge to Notion
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Webhook server listening on port ${PORT}`));

Deployment notes:

• Publish to a public HTTPS service (Heroku, Render, etc.).
• In Notion’s integration settings, add the endpoint URL (e.g., https://myapp.herokuapp.com/notion-webhook).
• Set NOTION_SECRET as an environment variable.
• Verify that the server logs the payload when you edit a page.
• Simulate a 500 response by inserting res.sendStatus(500); and confirm that Notion retries (check retry count in logs).

2. Polling Script (Node.js)

// poller.js
const fetch = require('node-fetch');
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const DATABASE_ID = process.env.DATABASE_ID;
const POLL_INTERVAL_MS = 30 * 1000; // 30 seconds

let lastCursor = null;

async function poll() {
  try {
    const response = await notion.databases.query({
      database_id: DATABASE_ID,
      start_cursor: lastCursor,
      page_size: 10,
    });

    if (response.has_more) {
      lastCursor = response.next_cursor;
    }

    console.log(`Fetched ${response.results.length} pages`);
    // Process new pages or changes here
  } catch (err) {
    console.error('❌  Polling error:', err.message);
  }
}

setInterval(poll, POLL_INTERVAL_MS);
console.log('Polling started – interval:', POLL_INTERVAL_MS / 1000, 'seconds');

Deployment notes:

• Set NOTION_TOKEN and DATABASE_ID as environment variables.
• Run the script locally or in a container.
• Verify that new changes appear in the console output.
• Ensure you do not exceed 50 calls per minute; the 30‑second interval stays well below this limit.

Verification Checklist

1. Webhook: Deploy the Express server, register the URL, edit a page, and confirm payload logging.
2. Simulate a server error (return 500) and observe Notion’s retry attempts.
3. Polling: Run the script, edit a page, and see the new page appear in the output within the next poll cycle.
4. Check that the number of API calls remains below 50 per minute to avoid throttling.

Limitations & Practical Tips

• Webhooks require a stable internet connection; temporary outages will cause missed events unless you implement a dead‑letter queue.
• Polling can introduce drift if the server clock is inaccurate; consider synchronizing with NTP.
• Both methods need the integration to have appropriate permissions on the target workspace.
• Always keep your integration secret and token out of source control.

Bottom Line

Use webhooks when you need low latency and can expose a public HTTPS endpoint. Opt for polling if you prefer simplicity, have strict network constraints, or can tolerate a few seconds of delay. The provided Node.js snippets give you a quick way to test each approach and confirm that your integration behaves as expected.