notion-webhooks-events

# Notion Webhooks & Event Handling ## Overview Notion offers three approaches to change detection, each with different trade-offs: | Approach | Latency | Complexity | Reliability | |----------|---------|------------|-------------| | **Polling with `search` / `databases.query`** | 30s-5min (your poll interval) | Low | High — you control timing | | **Native webhooks** (API 2025-02+) | Near real-time | Medium | Good — requires HTTPS endpoint, retry handling | | **Third-party connectors** (Zapier, Make) | 1-15 min | Low (no-code) | Vendor-dependent | **Honest assessment:** Notion's native webhook support arrived in mid-2025 and covers page, database, comment, and data source events. It works well for event notification but does not deliver full payloads — you still need API calls to fetch the changed data. For many use cases, especially incremental sync and backup, polling with `last_edited_time` filters remains the most battle-tested pattern. ## Prerequisites - `@notionhq/client` v2.3+ installed (`npm install @notionhq/client`) - Notion integration created at https://www.notion.so/my-integrations - Integration shared with target pages/databases (Connections menu in Notion) - `NOTION_TOKEN` environment variable set to the integration's Internal Integration Secret - For native webhooks: HTTPS endpoint accessible from the internet ## Instructions ### Step 1: Polling-Based Change Detection Polling is the most reliable approach and works with every Notion API version. Use `n...