Agent skill · software engineering · jeremylongshore
notion-webhooks-events
Implement verified Notion connection-webhook intake with deduplication, bounded processing, and fetch-current reconciliation. Use when reacting to workspace change signals. Trigger with "handle Notion webhooks", "verify Notion signature", or "reconcile Notion events".
Why this skill is useful
Provides specific implementation patterns and API usage for Notion's change detection that the AI wouldn't reliably generate on its own.
What it needs
Requires @notionhq/client installed locally. Requires notion account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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. Instructions 1. Define subscribed event types, data owner, destination, retention, and current subscription API version. 2. Implement the verification handshake without logging or echoing the token beyond the required portal step. 3. Verify the raw-body signature before JSON parsing or queue acknowledgement. 4. Persist a deduplication key, event timestamp, entity identity, attempt, and processing state with tenant binding. 5. Acknowledge quickly, process asynchronously, fetch current state, and make downstream work idempotent. 6. Reconcile periodically for missed, aggregated, reordered, duplicated, or stale signals. Tool Discipline Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/notion-webhooks-events--2bd2e3