fusionauth-webhooks

Name: fusionauth-webhooks
Author: hookdeck

80stars10forks

How to install fusionauth-webhooks?

hookdeck/webhook-skills/fusionauth-webhooks

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

Installs into the current project.

Summary

Receive and verify FusionAuth webhooks. Use when setting up FusionAuth webhook handlers, debugging JWT signature verification, or handling authentication events like user.create, user.login.success, user.registration.create, or user.delete.

Files · 1

View on GitHub

SKILL.md

1	# FusionAuth Webhooks
2
3	## When to Use This Skill
4
5	- Setting up FusionAuth webhook handlers
6	- Debugging JWT signature verification failures
7	- Understanding FusionAuth event types and payloads
8	- Handling user, login, registration, or group events
9
10	## Essential Code (USE THIS)
11
12	### FusionAuth Signature Verification (JavaScript)
13
14	FusionAuth signs webhooks with a JWT in the `X-FusionAuth-Signature-JWT` header. The JWT contains a `request_body_sha256` claim with the SHA-256 hash of the request body.
15
16	```javascript
17	const crypto = require('crypto');
18	const jose = require('jose');
19
20	// Verify FusionAuth webhook signature
21	async function verifyFusionAuthWebhook(rawBody, signatureJwt, hmacSecret) {
22	if (!signatureJwt \|\| !hmacSecret) return false;
23
24	try {
25	// Create key from HMAC secret
26	const key = new TextEncoder().encode(hmacSecret);
27
28	// Verify JWT signature and decode
29	const { payload } = await jose.jwtVerify(signatureJwt, key, {
30	algorithms: ['HS256', 'HS384', 'HS512']
31	});
32
33	// Calculate SHA-256 hash of request body
34	const bodyHash = crypto
35	.createHash('sha256')
36	.update(rawBody)
37	.digest('base64');
38
39	// Compare hash from JWT claim with calculated hash
40	return payload.request_body_sha256 === bodyHash;
41	} catch (err) {
42	console.error('JWT verification failed:', err.message);
43	return false;
44	}
45	}
46	```
47
48	### Express Webhook Handler
49
50	```javascript
51	const express = require('express');
52	const crypto = require('crypto');
53	const jose = require('jose');
54
55	const app = express();
56
57	// CRITICAL: Use express.raw() - FusionAuth needs raw body for signature verification
58	app.post('/webhooks/fusionauth',
59	express.raw({ type: 'application/json' }),
60	async (req, res) => {
61	const signatureJwt = req.headers['x-fusionauth-signature-jwt'];
62
63	// Verify signature
64	const isValid = await verifyFusionAuthWebhook(
65	req.body,
66	signatureJwt,
67	process.env.FUSIONAUTH_WEBHOOK_SECRET // HMAC signing key from FusionAuth
68	);
69
70	if (!isValid) {
71	console.error('FusionAuth signature verification failed');
72	return res.status(401).send('Invalid signature');
73	}
74
75	// Parse payload after verification
76	const event = JSON.parse(req.body.toString());
77
78	console.log(`Received event: ${event.event.type}`);
79
80	// Handle by event type
81	switch (event.event.type) {
82	case 'user.create':
83	console.log('User created:', event.event.user?.id);
84	break;
85	case 'user.update':
86	console.log('User updated:', event.event.user?.id);
87	break;
88	case 'user.login.success':
89	console.log('User logged in:', event.event.user?.id);
90	break;
91	case 'user.registration.create':
92	console.log('User registered:', event.event.user?.id);
93	break;
94	default:
95	console.log('Unhandled event:', event.event.type);
96	}
97
98	res.json({ received: true });
99	}
100	);
101	```
102
103	### Python (FastAPI) Webhook Handler
104
105	```python
106	import os
107	import hashlib
108	import base64
109	from fastapi import FastAPI, Request, HTTPException
110	import jwt
111
112	webhook_secret = os.environ.get("FUSIONAUTH_WEBHOOK_SECRET")
113
114	def verify_fusionauth_webhook(raw_body: bytes, signature_jwt: str, secret: str) -> bool:
115	if not signature_jwt or not secret:
116	return False
117
118	try:
119	# Verify and decode JWT
120	payload = jwt.decode(signature_jwt, secret, algorithms=['HS256', 'HS384', 'HS512'])
121
122	# Calculate SHA-256 hash of request body
123	body_hash = base64.b64encode(hashlib.sha256(raw_body).digest()).decode()
124
125	# Compare hash from JWT claim with calculated hash
126	return payload.get('request_body_sha256') == body_hash
127	except jwt.InvalidTokenError as e:
128	print(f"JWT verification failed: {e}")
129	return False
130
131	@app.post("/webhooks/fusionauth")
132	async def fusionauth_webhook(request: Request):
133	payload = await request.body()
134	signature_jwt = request.headers.get("x-fusionauth-signature-jwt")
135
136	if not verify_fusionauth_webhook(payload, signature_jwt, webhook_secret):
137	raise HTTPException(status_code=401, detail="Invalid signature")
138
139	# Handle event...
140	return {"received": True}
141	```
142
143	> For complete working examples with tests, see:
144	> - [examples/express/](examples/express/) - Full Express implementation
145	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
146	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
147
148	## Common Event Types
149
150	\| Event \| Description \|
151	\|-------\|-------------\|
152	\| `user.create` \| New user account created \|
153	\| `user.update` \| User pro

People who liked this also viewed

6 picks

Type

fusionauth-webhooks

80stars10forks

View on GitHub

How to install fusionauth-webhooks?

hookdeck/webhook-skills/fusionauth-webhooks

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# FusionAuth Webhooks
2
3	## When to Use This Skill
4
5	- Setting up FusionAuth webhook handlers
6	- Debugging JWT signature verification failures
7	- Understanding FusionAuth event types and payloads
8	- Handling user, login, registration, or group events
9
10	## Essential Code (USE THIS)
11
12	### FusionAuth Signature Verification (JavaScript)
13
14	FusionAuth signs webhooks with a JWT in the `X-FusionAuth-Signature-JWT` header. The JWT contains a `request_body_sha256` claim with the SHA-256 hash of the request body.
15
16	```javascript
17	const crypto = require('crypto');
18	const jose = require('jose');
19
20	// Verify FusionAuth webhook signature
21	async function verifyFusionAuthWebhook(rawBody, signatureJwt, hmacSecret) {
22	if (!signatureJwt \|\| !hmacSecret) return false;
23
24	try {
25	// Create key from HMAC secret
26	const key = new TextEncoder().encode(hmacSecret);
27
28	// Verify JWT signature and decode
29	const { payload } = await jose.jwtVerify(signatureJwt, key, {
30	algorithms: ['HS256', 'HS384', 'HS512']
31	});
32
33	// Calculate SHA-256 hash of request body
34	const bodyHash = crypto
35	.createHash('sha256')
36	.update(rawBody)
37	.digest('base64');
38
39	// Compare hash from JWT claim with calculated hash
40	return payload.request_body_sha256 === bodyHash;
41	} catch (err) {
42	console.error('JWT verification failed:', err.message);
43	return false;
44	}
45	}
46	```
47
48	### Express Webhook Handler
49
50	```javascript
51	const express = require('express');
52	const crypto = require('crypto');
53	const jose = require('jose');
54
55	const app = express();
56
57	// CRITICAL: Use express.raw() - FusionAuth needs raw body for signature verification
58	app.post('/webhooks/fusionauth',
59	express.raw({ type: 'application/json' }),
60	async (req, res) => {
61	const signatureJwt = req.headers['x-fusionauth-signature-jwt'];
62
63	// Verify signature
64	const isValid = await verifyFusionAuthWebhook(
65	req.body,
66	signatureJwt,
67	process.env.FUSIONAUTH_WEBHOOK_SECRET // HMAC signing key from FusionAuth
68	);
69
70	if (!isValid) {
71	console.error('FusionAuth signature verification failed');
72	return res.status(401).send('Invalid signature');
73	}
74
75	// Parse payload after verification
76	const event = JSON.parse(req.body.toString());
77
78	console.log(`Received event: ${event.event.type}`);
79
80	// Handle by event type
81	switch (event.event.type) {
82	case 'user.create':
83	console.log('User created:', event.event.user?.id);
84	break;
85	case 'user.update':
86	console.log('User updated:', event.event.user?.id);
87	break;
88	case 'user.login.success':
89	console.log('User logged in:', event.event.user?.id);
90	break;
91	case 'user.registration.create':
92	console.log('User registered:', event.event.user?.id);
93	break;
94	default:
95	console.log('Unhandled event:', event.event.type);
96	}
97
98	res.json({ received: true });
99	}
100	);
101	```
102
103	### Python (FastAPI) Webhook Handler
104
105	```python
106	import os
107	import hashlib
108	import base64
109	from fastapi import FastAPI, Request, HTTPException
110	import jwt
111
112	webhook_secret = os.environ.get("FUSIONAUTH_WEBHOOK_SECRET")
113
114	def verify_fusionauth_webhook(raw_body: bytes, signature_jwt: str, secret: str) -> bool:
115	if not signature_jwt or not secret:
116	return False
117
118	try:
119	# Verify and decode JWT
120	payload = jwt.decode(signature_jwt, secret, algorithms=['HS256', 'HS384', 'HS512'])
121
122	# Calculate SHA-256 hash of request body
123	body_hash = base64.b64encode(hashlib.sha256(raw_body).digest()).decode()
124
125	# Compare hash from JWT claim with calculated hash
126	return payload.get('request_body_sha256') == body_hash
127	except jwt.InvalidTokenError as e:
128	print(f"JWT verification failed: {e}")
129	return False
130
131	@app.post("/webhooks/fusionauth")
132	async def fusionauth_webhook(request: Request):
133	payload = await request.body()
134	signature_jwt = request.headers.get("x-fusionauth-signature-jwt")
135
136	if not verify_fusionauth_webhook(payload, signature_jwt, webhook_secret):
137	raise HTTPException(status_code=401, detail="Invalid signature")
138
139	# Handle event...
140	return {"received": True}
141	```
142
143	> For complete working examples with tests, see:
144	> - [examples/express/](examples/express/) - Full Express implementation
145	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
146	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
147
148	## Common Event Types
149
150	\| Event \| Description \|
151	\|-------\|-------------\|
152	\| `user.create` \| New user account created \|
153	\| `user.update` \| User pro

People who liked this also viewed

6 picks

Type