notion-webhooks

Name: notion-webhooks
Author: hookdeck

80stars10forks

How to install notion-webhooks?

hookdeck/webhook-skills/notion-webhooks

$npx -y skills add hookdeck/webhook-skills --skill notion-webhooks

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Notion Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Notion webhook handlers for an internal integration
6	- Debugging Notion signature verification failures
7	- Completing the one-time `verification_token` handshake to activate a subscription
8	- Handling page, comment, database, or data source events from a Notion workspace
9
10	## Essential Code (USE THIS)
11
12	Notion uses HMAC-SHA256 over the raw request body with the integration's
13	`verification_token` as the signing key. The signature is sent in the
14	`X-Notion-Signature` header in the format `sha256=<hex_digest>`.
15
16	The first POST to a new subscription is a handshake: it contains a
17	`verification_token` in the JSON body and has no signature. The handler
18	must capture the token (log it, store it, surface it in your dashboard), then
19	the developer pastes it into the Notion integration UI to activate the
20	subscription. All subsequent deliveries are signed with that token.
21
22	### Notion Signature Verification (JavaScript)
23
24	```javascript
25	const crypto = require('crypto');
26
27	function verifyNotionSignature(rawBody, signatureHeader, verificationToken) {
28	if (!signatureHeader \|\| !verificationToken) return false;
29
30	// Notion sends: sha256=<hex>
31	const expected = `sha256=${crypto
32	.createHmac('sha256', verificationToken)
33	.update(rawBody)
34	.digest('hex')}`;
35
36	try {
37	return crypto.timingSafeEqual(
38	Buffer.from(expected),
39	Buffer.from(signatureHeader)
40	);
41	} catch {
42	return false;
43	}
44	}
45	```
46
47	### Express Webhook Handler
48
49	```javascript
50	const express = require('express');
51	const app = express();
52
53	// CRITICAL: Use express.raw() - Notion requires raw body for signature verification
54	app.post('/webhooks/notion',
55	express.raw({ type: 'application/json' }),
56	(req, res) => {
57	const signature = req.headers['x-notion-signature'];
58	const token = process.env.NOTION_VERIFICATION_TOKEN;
59
60	// Handshake: first delivery has no signature and contains verification_token
61	if (!signature) {
62	try {
63	const parsed = JSON.parse(req.body.toString('utf8'));
64	if (parsed && parsed.verification_token) {
65	console.log('Notion verification_token (paste into Notion UI):', parsed.verification_token);
66	return res.status(200).json({ received: true });
67	}
68	} catch { /* fall through */ }
69	return res.status(400).send('Missing X-Notion-Signature');
70	}
71
72	if (!verifyNotionSignature(req.body, signature, token)) {
73	return res.status(401).send('Invalid signature');
74	}
75
76	const event = JSON.parse(req.body.toString('utf8'));
77
78	switch (event.type) {
79	case 'page.content_updated':
80	console.log('Page content updated:', event.entity?.id);
81	break;
82	case 'page.properties_updated':
83	console.log('Page properties updated:', event.entity?.id);
84	break;
85	case 'comment.created':
86	console.log('Comment created:', event.entity?.id);
87	break;
88	case 'data_source.schema_updated':
89	console.log('Data source schema updated:', event.entity?.id);
90	break;
91	default:
92	console.log('Unhandled event:', event.type);
93	}
94
95	res.json({ received: true });
96	}
97	);
98	```
99
100	### Python (FastAPI) Verification
101
102	```python
103	import hmac, hashlib, json
104	from fastapi import FastAPI, Request, HTTPException
105
106	def verify_notion_signature(raw_body: bytes, signature_header: str, token: str) -> bool:
107	if not signature_header or not token:
108	return False
109	expected = "sha256=" + hmac.new(
110	token.encode("utf-8"), raw_body, hashlib.sha256
111	).hexdigest()
112	return hmac.compare_digest(expected, signature_header)
113
114	@app.post("/webhooks/notion")
115	async def notion_webhook(request: Request):
116	raw = await request.body()
117	signature = request.headers.get("x-notion-signature")
118
119	# Handshake: first delivery has no signature and contains verification_token
120	if not signature:
121	try:
122	data = json.loads(raw)
123	if "verification_token" in data:
124	print("Notion verification_token:", data["verification_token"])
125	return {"received": True}
126	except Exception:
127	pass
128	raise HTTPException(status_code=400, detail="Missing X-Notion-Signature")
129
130	if not verify_notion_signature(raw, signature, os.environ["NOTION_VERIFICATION_TOKEN"]):
131	raise HTTPException(status_code=401, detail="Invalid signature")
132
133	event = json.loads(raw)
134	# handle event.type ...
135	return {"received": True}
136	```
137
138	> **For complete working example

People who liked this also viewed

6 picks

Type

notion-webhooks

80stars10forks

View on GitHub

How to install notion-webhooks?

hookdeck/webhook-skills/notion-webhooks

$npx -y skills add hookdeck/webhook-skills --skill notion-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Notion Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Notion webhook handlers for an internal integration
6	- Debugging Notion signature verification failures
7	- Completing the one-time `verification_token` handshake to activate a subscription
8	- Handling page, comment, database, or data source events from a Notion workspace
9
10	## Essential Code (USE THIS)
11
12	Notion uses HMAC-SHA256 over the raw request body with the integration's
13	`verification_token` as the signing key. The signature is sent in the
14	`X-Notion-Signature` header in the format `sha256=<hex_digest>`.
15
16	The first POST to a new subscription is a handshake: it contains a
17	`verification_token` in the JSON body and has no signature. The handler
18	must capture the token (log it, store it, surface it in your dashboard), then
19	the developer pastes it into the Notion integration UI to activate the
20	subscription. All subsequent deliveries are signed with that token.
21
22	### Notion Signature Verification (JavaScript)
23
24	```javascript
25	const crypto = require('crypto');
26
27	function verifyNotionSignature(rawBody, signatureHeader, verificationToken) {
28	if (!signatureHeader \|\| !verificationToken) return false;
29
30	// Notion sends: sha256=<hex>
31	const expected = `sha256=${crypto
32	.createHmac('sha256', verificationToken)
33	.update(rawBody)
34	.digest('hex')}`;
35
36	try {
37	return crypto.timingSafeEqual(
38	Buffer.from(expected),
39	Buffer.from(signatureHeader)
40	);
41	} catch {
42	return false;
43	}
44	}
45	```
46
47	### Express Webhook Handler
48
49	```javascript
50	const express = require('express');
51	const app = express();
52
53	// CRITICAL: Use express.raw() - Notion requires raw body for signature verification
54	app.post('/webhooks/notion',
55	express.raw({ type: 'application/json' }),
56	(req, res) => {
57	const signature = req.headers['x-notion-signature'];
58	const token = process.env.NOTION_VERIFICATION_TOKEN;
59
60	// Handshake: first delivery has no signature and contains verification_token
61	if (!signature) {
62	try {
63	const parsed = JSON.parse(req.body.toString('utf8'));
64	if (parsed && parsed.verification_token) {
65	console.log('Notion verification_token (paste into Notion UI):', parsed.verification_token);
66	return res.status(200).json({ received: true });
67	}
68	} catch { /* fall through */ }
69	return res.status(400).send('Missing X-Notion-Signature');
70	}
71
72	if (!verifyNotionSignature(req.body, signature, token)) {
73	return res.status(401).send('Invalid signature');
74	}
75
76	const event = JSON.parse(req.body.toString('utf8'));
77
78	switch (event.type) {
79	case 'page.content_updated':
80	console.log('Page content updated:', event.entity?.id);
81	break;
82	case 'page.properties_updated':
83	console.log('Page properties updated:', event.entity?.id);
84	break;
85	case 'comment.created':
86	console.log('Comment created:', event.entity?.id);
87	break;
88	case 'data_source.schema_updated':
89	console.log('Data source schema updated:', event.entity?.id);
90	break;
91	default:
92	console.log('Unhandled event:', event.type);
93	}
94
95	res.json({ received: true });
96	}
97	);
98	```
99
100	### Python (FastAPI) Verification
101
102	```python
103	import hmac, hashlib, json
104	from fastapi import FastAPI, Request, HTTPException
105
106	def verify_notion_signature(raw_body: bytes, signature_header: str, token: str) -> bool:
107	if not signature_header or not token:
108	return False
109	expected = "sha256=" + hmac.new(
110	token.encode("utf-8"), raw_body, hashlib.sha256
111	).hexdigest()
112	return hmac.compare_digest(expected, signature_header)
113
114	@app.post("/webhooks/notion")
115	async def notion_webhook(request: Request):
116	raw = await request.body()
117	signature = request.headers.get("x-notion-signature")
118
119	# Handshake: first delivery has no signature and contains verification_token
120	if not signature:
121	try:
122	data = json.loads(raw)
123	if "verification_token" in data:
124	print("Notion verification_token:", data["verification_token"])
125	return {"received": True}
126	except Exception:
127	pass
128	raise HTTPException(status_code=400, detail="Missing X-Notion-Signature")
129
130	if not verify_notion_signature(raw, signature, os.environ["NOTION_VERIFICATION_TOKEN"]):
131	raise HTTPException(status_code=401, detail="Invalid signature")
132
133	event = json.loads(raw)
134	# handle event.type ...
135	return {"received": True}
136	```
137
138	> **For complete working example

People who liked this also viewed

6 picks

Type