All Docs
FeaturesSidekickUpdated March 11, 2026

Notion Integration: Polling Architecture & Webhook Behaviour

Notion Integration: Polling Architecture & Webhook Behaviour

The Sidekick Notion integration uses a polling-based synchronisation model rather than webhooks. This page documents the design, explains the intentional asymmetry between Notion and webhook-driven adapters, and clarifies what to expect if you interact with the generic webhook route for Notion.

How the Notion Adapter Works

Notion does not provide outbound webhooks for real-time event delivery (as of this release). Sidekick therefore uses a scheduled poll-based sync to keep your Notion workspace in sync:

  • The sync-poll-integrations cron job periodically calls the Notion adapter.
  • The adapter queries the Notion API for changes since the last sync.
  • Results are normalised through the standard unified adapter interface and ingested into Sidekick's event pipeline.

This is transparent to the end user — your Notion pages, databases, and comments are kept up to date automatically without any extra configuration.

Adapter Registration

The Notion adapter is registered in the central adapter index (src/lib/integrations/adapters/notion/index.ts) alongside all other integrations. This registration is required for the polling cron to discover and invoke it.

Key architectural points

PropertyNotion AdapterWebhook-based Adapters
Sync mechanismCron polling (sync-poll-integrations)Inbound webhook (/api/webhooks/[adapter_id])
Webhook routeNone (intentional)/api/webhooks/[adapter_id]
Dedup index inclusion❌ Excluded (intentional)✅ Included
Real-time deliveryNo (poll interval applies)Yes

Webhook Route Behaviour

Because Notion is a polling adapter, there is no dedicated /api/webhooks/notion route. The platform's generic /api/webhooks/[adapter_id] route will still accept a request to /api/webhooks/notion without error, returning:

{
  "processed": 0
}

with an HTTP 200 status. This is safe and expected — it simply means no webhook events were dispatched. This response should not be interpreted as an error.

Note: If you are building a custom integration or skill that targets Notion, do not attempt to configure Notion to push webhook events to this endpoint. Use the polling cron path instead.

Deduplication

Webhook-driven adapters are registered in the webhook dedup index to prevent the same inbound event from being processed twice (e.g. if a third-party service retries delivery). The Notion adapter is not included in this index — this is intentional.

Deduplication for polling-based adapters is handled at the cron layer, where each poll records a cursor or timestamp so previously-seen items are not reprocessed.

Future Webhook Support

If Notion introduces official webhook support in the future, the adapter will be updated to:

  1. Register a dedicated /api/webhooks/notion route handler.
  2. Be included in the webhook dedup index.
  3. Optionally retain polling as a fallback for accounts where webhook registration is unavailable.

No changes are needed today.

Related