hubspot-webhooks

Name: hubspot-webhooks
Author: hookdeck

80stars10forks

How to install hubspot-webhooks?

hookdeck/webhook-skills/hubspot-webhooks

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

Installs into the current project.

Summary

Receive and verify HubSpot webhooks. Use when setting up HubSpot webhook handlers, debugging X-HubSpot-Signature-v3 signature verification, or handling CRM events like contact.creation, contact.propertyChange, or deal.creation.

Files · 1

View on GitHub

SKILL.md

1	# HubSpot Webhooks
2
3	## When to Use This Skill
4
5	- Setting up HubSpot webhook handlers
6	- Verifying `X-HubSpot-Signature-v3` headers
7	- Debugging signature verification failures
8	- Handling CRM events like contact creation, property changes, or deal events
9	- Migrating from HubSpot signature v1/v2 to v3
10
11	## Essential Code (USE THIS)
12
13	HubSpot does not provide an SDK helper for webhook signature verification, so verification is implemented manually with HMAC-SHA256 and base64 across all frameworks.
14
15	### HubSpot Signature Verification (JavaScript)
16
17	```javascript
18	const crypto = require('crypto');
19
20	const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
21
22	/**
23	* Verify HubSpot v3 webhook signature.
24	*
25	* Signed content = HTTP method + request URI + raw body + timestamp
26	* Signature is HMAC-SHA256 (base64) of that string using the app's Client Secret.
27	*/
28	function verifyHubSpotWebhook({ method, uri, rawBody, timestamp, signature, secret }) {
29	if (!signature \|\| !timestamp \|\| !secret) return false;
30
31	// Reject stale requests (older than 5 minutes)
32	const ts = Number(timestamp);
33	if (!Number.isFinite(ts) \|\| Math.abs(Date.now() - ts) > MAX_AGE_MS) return false;
34
35	const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
36	const signedContent = `${method}${uri}${body}${timestamp}`;
37
38	const expected = crypto
39	.createHmac('sha256', secret)
40	.update(signedContent, 'utf8')
41	.digest('base64');
42
43	try {
44	return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
45	} catch {
46	return false;
47	}
48	}
49	```
50
51	### Express Webhook Handler
52
53	```javascript
54	const express = require('express');
55	const app = express();
56
57	// CRITICAL: Use express.raw() - HubSpot requires raw body for HMAC verification
58	app.post('/webhooks/hubspot',
59	express.raw({ type: 'application/json' }),
60	(req, res) => {
61	const signature = req.headers['x-hubspot-signature-v3'];
62	const timestamp = req.headers['x-hubspot-request-timestamp'];
63
64	// Reconstruct the full request URI (HubSpot signs the URL it called)
65	const uri = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
66
67	const valid = verifyHubSpotWebhook({
68	method: req.method,
69	uri,
70	rawBody: req.body,
71	timestamp,
72	signature,
73	secret: process.env.HUBSPOT_CLIENT_SECRET,
74	});
75
76	if (!valid) {
77	console.error('HubSpot signature verification failed');
78	return res.status(400).send('Invalid signature');
79	}
80
81	// HubSpot sends an array of events in each webhook
82	const events = JSON.parse(req.body.toString());
83
84	for (const event of events) {
85	switch (event.subscriptionType) {
86	case 'contact.creation':
87	console.log('New contact:', event.objectId);
88	break;
89	case 'contact.propertyChange':
90	console.log('Contact property changed:', event.objectId, event.propertyName);
91	break;
92	case 'deal.creation':
93	console.log('New deal:', event.objectId);
94	break;
95	default:
96	console.log('Unhandled event:', event.subscriptionType);
97	}
98	}
99
100	res.status(200).send('OK');
101	}
102	);
103	```
104
105	### Python (FastAPI) Signature Verification
106
107	```python
108	import hmac
109	import hashlib
110	import base64
111	import time
112
113	MAX_AGE_MS = 5 * 60 * 1000 # 5 minutes
114
115	def verify_hubspot_webhook(method: str, uri: str, raw_body: bytes,
116	timestamp: str, signature: str, secret: str) -> bool:
117	if not signature or not timestamp or not secret:
118	return False
119
120	try:
121	ts = int(timestamp)
122	except ValueError:
123	return False
124
125	if abs(int(time.time() * 1000) - ts) > MAX_AGE_MS:
126	return False
127
128	body = raw_body.decode("utf-8")
129	signed_content = f"{method}{uri}{body}{timestamp}"
130
131	expected = base64.b64encode(
132	hmac.new(secret.encode("utf-8"), signed_content.encode("utf-8"), hashlib.sha256).digest()
133	).decode("utf-8")
134
135	return hmac.compare_digest(expected, signature)
136	```
137
138	> For complete working examples with tests, see:
139	> - [examples/express/](examples/express/) - Full Express implementation
140	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
141	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
142
143	## Common Event Types
144
145	HubSpot calls these `subscriptionType` values. Each webhook delivery contains an array of one or more event objects.
146
147	\| Event \| Description \|
148	\|-------\|-------------\|
149	\| `contact.creation` \| A new contact was created \|
150	\| `contact.propertyChange` \| A property on a contact changed \|
151	\| `contact.deletion` \| A contact was deleted \|
152	\| `company.creation

People who liked this also viewed

6 picks

Type

hubspot-webhooks

80stars10forks

View on GitHub

How to install hubspot-webhooks?

hookdeck/webhook-skills/hubspot-webhooks

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# HubSpot Webhooks
2
3	## When to Use This Skill
4
5	- Setting up HubSpot webhook handlers
6	- Verifying `X-HubSpot-Signature-v3` headers
7	- Debugging signature verification failures
8	- Handling CRM events like contact creation, property changes, or deal events
9	- Migrating from HubSpot signature v1/v2 to v3
10
11	## Essential Code (USE THIS)
12
13	HubSpot does not provide an SDK helper for webhook signature verification, so verification is implemented manually with HMAC-SHA256 and base64 across all frameworks.
14
15	### HubSpot Signature Verification (JavaScript)
16
17	```javascript
18	const crypto = require('crypto');
19
20	const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
21
22	/**
23	* Verify HubSpot v3 webhook signature.
24	*
25	* Signed content = HTTP method + request URI + raw body + timestamp
26	* Signature is HMAC-SHA256 (base64) of that string using the app's Client Secret.
27	*/
28	function verifyHubSpotWebhook({ method, uri, rawBody, timestamp, signature, secret }) {
29	if (!signature \|\| !timestamp \|\| !secret) return false;
30
31	// Reject stale requests (older than 5 minutes)
32	const ts = Number(timestamp);
33	if (!Number.isFinite(ts) \|\| Math.abs(Date.now() - ts) > MAX_AGE_MS) return false;
34
35	const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
36	const signedContent = `${method}${uri}${body}${timestamp}`;
37
38	const expected = crypto
39	.createHmac('sha256', secret)
40	.update(signedContent, 'utf8')
41	.digest('base64');
42
43	try {
44	return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
45	} catch {
46	return false;
47	}
48	}
49	```
50
51	### Express Webhook Handler
52
53	```javascript
54	const express = require('express');
55	const app = express();
56
57	// CRITICAL: Use express.raw() - HubSpot requires raw body for HMAC verification
58	app.post('/webhooks/hubspot',
59	express.raw({ type: 'application/json' }),
60	(req, res) => {
61	const signature = req.headers['x-hubspot-signature-v3'];
62	const timestamp = req.headers['x-hubspot-request-timestamp'];
63
64	// Reconstruct the full request URI (HubSpot signs the URL it called)
65	const uri = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
66
67	const valid = verifyHubSpotWebhook({
68	method: req.method,
69	uri,
70	rawBody: req.body,
71	timestamp,
72	signature,
73	secret: process.env.HUBSPOT_CLIENT_SECRET,
74	});
75
76	if (!valid) {
77	console.error('HubSpot signature verification failed');
78	return res.status(400).send('Invalid signature');
79	}
80
81	// HubSpot sends an array of events in each webhook
82	const events = JSON.parse(req.body.toString());
83
84	for (const event of events) {
85	switch (event.subscriptionType) {
86	case 'contact.creation':
87	console.log('New contact:', event.objectId);
88	break;
89	case 'contact.propertyChange':
90	console.log('Contact property changed:', event.objectId, event.propertyName);
91	break;
92	case 'deal.creation':
93	console.log('New deal:', event.objectId);
94	break;
95	default:
96	console.log('Unhandled event:', event.subscriptionType);
97	}
98	}
99
100	res.status(200).send('OK');
101	}
102	);
103	```
104
105	### Python (FastAPI) Signature Verification
106
107	```python
108	import hmac
109	import hashlib
110	import base64
111	import time
112
113	MAX_AGE_MS = 5 * 60 * 1000 # 5 minutes
114
115	def verify_hubspot_webhook(method: str, uri: str, raw_body: bytes,
116	timestamp: str, signature: str, secret: str) -> bool:
117	if not signature or not timestamp or not secret:
118	return False
119
120	try:
121	ts = int(timestamp)
122	except ValueError:
123	return False
124
125	if abs(int(time.time() * 1000) - ts) > MAX_AGE_MS:
126	return False
127
128	body = raw_body.decode("utf-8")
129	signed_content = f"{method}{uri}{body}{timestamp}"
130
131	expected = base64.b64encode(
132	hmac.new(secret.encode("utf-8"), signed_content.encode("utf-8"), hashlib.sha256).digest()
133	).decode("utf-8")
134
135	return hmac.compare_digest(expected, signature)
136	```
137
138	> For complete working examples with tests, see:
139	> - [examples/express/](examples/express/) - Full Express implementation
140	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
141	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
142
143	## Common Event Types
144
145	HubSpot calls these `subscriptionType` values. Each webhook delivery contains an array of one or more event objects.
146
147	\| Event \| Description \|
148	\|-------\|-------------\|
149	\| `contact.creation` \| A new contact was created \|
150	\| `contact.propertyChange` \| A property on a contact changed \|
151	\| `contact.deletion` \| A contact was deleted \|
152	\| `company.creation

People who liked this also viewed

6 picks

Type