notion-webhooks

name	notion-webhooks
description	Receive and verify Notion webhooks. Use when setting up Notion webhook handlers, debugging Notion signature verification, completing the verification_token handshake, or handling workspace events like page.content_updated, page.properties_updated, comment.created, or data_source.schema_updated.
license	MIT
metadata	{"author":"hookdeck","version":"0.1.0","repository":"https://github.com/hookdeck/webhook-skills"}

Notion Webhooks

When to Use This Skill

• Setting up Notion webhook handlers for an internal integration
• Debugging Notion signature verification failures
• Completing the one-time verification_token handshake to activate a subscription
• Handling page, comment, database, or data source events from a Notion workspace

Essential Code (USE THIS)

Notion uses HMAC-SHA256 over the raw request body with the integration's verification_token as the signing key. The signature is sent in the X-Notion-Signature header in the format sha256=<hex_digest>.

The first POST to a new subscription is a handshake: it contains a verification_token in the JSON body and has no signature. The handler must capture the token (log it, store it, surface it in your dashboard), then the developer pastes it into the Notion integration UI to activate the subscription. All subsequent deliveries are signed with that token.