hookdeck-event-gateway-webhooks

Name: hookdeck-event-gateway-webhooks
Author: hookdeck

80stars10forks

How to install hookdeck-event-gateway-webhooks?

hookdeck/webhook-skills/hookdeck-event-gateway-webhooks

$npx -y skills add hookdeck/webhook-skills --skill hookdeck-event-gateway-webhooks

Installs into the current project.

Summary

Verify and handle webhooks delivered through the Hookdeck Event Gateway. Use when receiving webhooks via Hookdeck and need to verify the x-hookdeck-signature header. Covers signature verification for Express, Next.js, and FastAPI.

Files · 1

View on GitHub

SKILL.md

1	# Hookdeck Event Gateway Webhooks
2
3	When webhooks flow through the [Hookdeck Event Gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway), Hookdeck queues and delivers them to your app. Each forwarded request is signed with an `x-hookdeck-signature` header (HMAC SHA-256, base64). Your handler verifies this signature to confirm the request came from Hookdeck.
4
5	## When to Use This Skill
6
7	- Receiving webhooks through the Hookdeck Event Gateway (not directly from providers)
8	- Verifying the `x-hookdeck-signature` header on forwarded webhooks
9	- Using Hookdeck headers (event ID, source ID, attempt number) for idempotency and debugging
10	- Debugging Hookdeck signature verification failures
11
12	## Essential Code (USE THIS)
13
14	### Hookdeck Signature Verification (JavaScript/Node.js)
15
16	```javascript
17	const crypto = require('crypto');
18
19	function verifyHookdeckSignature(rawBody, signature, secret) {
20	if (!signature \|\| !secret) return false;
21
22	const hash = crypto
23	.createHmac('sha256', secret)
24	.update(rawBody)
25	.digest('base64');
26
27	try {
28	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
29	} catch {
30	return false;
31	}
32	}
33	```
34
35	### Hookdeck Signature Verification (Python)
36
37	```python
38	import hmac
39	import hashlib
40	import base64
41
42	def verify_hookdeck_signature(raw_body: bytes, signature: str, secret: str) -> bool:
43	if not signature or not secret:
44	return False
45	expected = base64.b64encode(
46	hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
47	).decode()
48	return hmac.compare_digest(signature, expected)
49	```
50
51	## Environment Variables
52
53	```bash
54	# Required for signature verification
55	# Get from Hookdeck Dashboard → Destinations → your destination → Webhook Secret
56	HOOKDECK_WEBHOOK_SECRET=your_webhook_secret_from_hookdeck_dashboard
57	```
58
59	## Express Webhook Handler
60
61	```javascript
62	const express = require('express');
63	const app = express();
64
65	// IMPORTANT: Use express.raw() for signature verification
66	app.post('/webhooks',
67	express.raw({ type: 'application/json' }),
68	(req, res) => {
69	const signature = req.headers['x-hookdeck-signature'];
70
71	if (!verifyHookdeckSignature(req.body, signature, process.env.HOOKDECK_WEBHOOK_SECRET)) {
72	console.error('Hookdeck signature verification failed');
73	return res.status(401).send('Invalid signature');
74	}
75
76	// Parse payload after verification
77	const payload = JSON.parse(req.body.toString());
78
79	// Handle the event (payload structure depends on original provider)
80	console.log('Event received:', payload.type \|\| payload.topic \|\| 'unknown');
81
82	// Return status code — Hookdeck retries on non-2xx
83	res.json({ received: true });
84	}
85	);
86	```
87
88	## Next.js Webhook Handler (App Router)
89
90	```typescript
91	import { NextRequest, NextResponse } from 'next/server';
92	import crypto from 'crypto';
93
94	function verifyHookdeckSignature(body: string, signature: string \| null, secret: string): boolean {
95	if (!signature \|\| !secret) return false;
96	const hash = crypto.createHmac('sha256', secret).update(body).digest('base64');
97	try {
98	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
99	} catch {
100	return false;
101	}
102	}
103
104	export async function POST(request: NextRequest) {
105	const body = await request.text();
106	const signature = request.headers.get('x-hookdeck-signature');
107
108	if (!verifyHookdeckSignature(body, signature, process.env.HOOKDECK_WEBHOOK_SECRET!)) {
109	return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
110	}
111
112	const payload = JSON.parse(body);
113	console.log('Event received:', payload.type \|\| payload.topic \|\| 'unknown');
114
115	return NextResponse.json({ received: true });
116	}
117	```
118
119	## FastAPI Webhook Handler
120
121	```python
122	import os
123	import json
124	from fastapi import FastAPI, Request, HTTPException
125
126	app = FastAPI()
127
128	@app.post("/webhooks")
129	async def webhook(request: Request):
130	raw_body = await request.body()
131	signature = request.headers.get("x-hookdeck-signature")
132
133	if not verify_hookdeck_signature(raw_body, signature, os.environ["HOOKDECK_WEBHOOK_SECRET"]):
134	raise HTTPException(status_code=401, detail="Invalid signature")
135
136	payload = json.loads(raw_body)
137	print(f"Event received: {payload.get('type', 'unknown')}")
138
139	return {"received": True}
140	```
141
142	> For complete working examples with tests, see:
143	> - [examples/express/](examples/express/) - Full Express implementation with tests
144	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation with tests
145	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI i

People who liked this also viewed

6 picks

Type

hookdeck-event-gateway-webhooks

80stars10forks

View on GitHub

How to install hookdeck-event-gateway-webhooks?

hookdeck/webhook-skills/hookdeck-event-gateway-webhooks

$npx -y skills add hookdeck/webhook-skills --skill hookdeck-event-gateway-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Hookdeck Event Gateway Webhooks
2
3	When webhooks flow through the [Hookdeck Event Gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway), Hookdeck queues and delivers them to your app. Each forwarded request is signed with an `x-hookdeck-signature` header (HMAC SHA-256, base64). Your handler verifies this signature to confirm the request came from Hookdeck.
4
5	## When to Use This Skill
6
7	- Receiving webhooks through the Hookdeck Event Gateway (not directly from providers)
8	- Verifying the `x-hookdeck-signature` header on forwarded webhooks
9	- Using Hookdeck headers (event ID, source ID, attempt number) for idempotency and debugging
10	- Debugging Hookdeck signature verification failures
11
12	## Essential Code (USE THIS)
13
14	### Hookdeck Signature Verification (JavaScript/Node.js)
15
16	```javascript
17	const crypto = require('crypto');
18
19	function verifyHookdeckSignature(rawBody, signature, secret) {
20	if (!signature \|\| !secret) return false;
21
22	const hash = crypto
23	.createHmac('sha256', secret)
24	.update(rawBody)
25	.digest('base64');
26
27	try {
28	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
29	} catch {
30	return false;
31	}
32	}
33	```
34
35	### Hookdeck Signature Verification (Python)
36
37	```python
38	import hmac
39	import hashlib
40	import base64
41
42	def verify_hookdeck_signature(raw_body: bytes, signature: str, secret: str) -> bool:
43	if not signature or not secret:
44	return False
45	expected = base64.b64encode(
46	hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
47	).decode()
48	return hmac.compare_digest(signature, expected)
49	```
50
51	## Environment Variables
52
53	```bash
54	# Required for signature verification
55	# Get from Hookdeck Dashboard → Destinations → your destination → Webhook Secret
56	HOOKDECK_WEBHOOK_SECRET=your_webhook_secret_from_hookdeck_dashboard
57	```
58
59	## Express Webhook Handler
60
61	```javascript
62	const express = require('express');
63	const app = express();
64
65	// IMPORTANT: Use express.raw() for signature verification
66	app.post('/webhooks',
67	express.raw({ type: 'application/json' }),
68	(req, res) => {
69	const signature = req.headers['x-hookdeck-signature'];
70
71	if (!verifyHookdeckSignature(req.body, signature, process.env.HOOKDECK_WEBHOOK_SECRET)) {
72	console.error('Hookdeck signature verification failed');
73	return res.status(401).send('Invalid signature');
74	}
75
76	// Parse payload after verification
77	const payload = JSON.parse(req.body.toString());
78
79	// Handle the event (payload structure depends on original provider)
80	console.log('Event received:', payload.type \|\| payload.topic \|\| 'unknown');
81
82	// Return status code — Hookdeck retries on non-2xx
83	res.json({ received: true });
84	}
85	);
86	```
87
88	## Next.js Webhook Handler (App Router)
89
90	```typescript
91	import { NextRequest, NextResponse } from 'next/server';
92	import crypto from 'crypto';
93
94	function verifyHookdeckSignature(body: string, signature: string \| null, secret: string): boolean {
95	if (!signature \|\| !secret) return false;
96	const hash = crypto.createHmac('sha256', secret).update(body).digest('base64');
97	try {
98	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
99	} catch {
100	return false;
101	}
102	}
103
104	export async function POST(request: NextRequest) {
105	const body = await request.text();
106	const signature = request.headers.get('x-hookdeck-signature');
107
108	if (!verifyHookdeckSignature(body, signature, process.env.HOOKDECK_WEBHOOK_SECRET!)) {
109	return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
110	}
111
112	const payload = JSON.parse(body);
113	console.log('Event received:', payload.type \|\| payload.topic \|\| 'unknown');
114
115	return NextResponse.json({ received: true });
116	}
117	```
118
119	## FastAPI Webhook Handler
120
121	```python
122	import os
123	import json
124	from fastapi import FastAPI, Request, HTTPException
125
126	app = FastAPI()
127
128	@app.post("/webhooks")
129	async def webhook(request: Request):
130	raw_body = await request.body()
131	signature = request.headers.get("x-hookdeck-signature")
132
133	if not verify_hookdeck_signature(raw_body, signature, os.environ["HOOKDECK_WEBHOOK_SECRET"]):
134	raise HTTPException(status_code=401, detail="Invalid signature")
135
136	payload = json.loads(raw_body)
137	print(f"Event received: {payload.get('type', 'unknown')}")
138
139	return {"received": True}
140	```
141
142	> For complete working examples with tests, see:
143	> - [examples/express/](examples/express/) - Full Express implementation with tests
144	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation with tests
145	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI i

People who liked this also viewed

6 picks

Type