Notion Webhook Intake and Reconciliation

Overview

Implement verified Notion connection-webhook intake with deduplication, bounded processing, and fetch-current reconciliation.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion verifies a subscription with a one-time token and signs later raw request bodies in X-Notion-Signature using HMAC-SHA256. Events can aggregate, arrive out of order, and omit full changed content; fetch current state and reconcile. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Store verification material as a secret, hash the exact raw body, compare signatures in constant time, bind the subscription to the expected connection, and rotate through an approved recreate path.