slack-webhooks

Name: slack-webhooks
Author: hookdeck

80stars10forks

How to install slack-webhooks?

hookdeck/webhook-skills/slack-webhooks

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

Installs into the current project.

Summary

Receive and verify Slack Events API webhooks. Use when setting up Slack webhook handlers, debugging Slack signature verification, handling the url_verification challenge, or processing events like app_mention, message, reaction_added, team_join, or app_home_opened.

Files · 1

View on GitHub

SKILL.md

1	# Slack Webhooks
2
3	## When to Use This Skill
4
5	- Setting up a Slack Events API webhook handler (Request URL)
6	- Debugging `X-Slack-Signature` verification failures
7	- Handling the initial `url_verification` challenge from Slack
8	- Processing events like `app_mention`, `message`, `reaction_added`, `team_join`, or `app_home_opened`
9	- Returning a 2xx response within 3 seconds to avoid Slack retries
10
11	## Essential Code (USE THIS)
12
13	Slack signs every Events API request with HMAC-SHA256. The signed content is the
14	literal string `v0:{timestamp}:{raw_body}`, and the result is sent as
15	`X-Slack-Signature: v0=<hex>`. Use the raw request body — parsing JSON
16	before verifying will change byte ordering and break the signature.
17
18	### Slack Signature Verification (JavaScript)
19
20	```javascript
21	const crypto = require('crypto');
22
23	function verifySlackRequest(rawBody, signatureHeader, timestampHeader, signingSecret) {
24	if (!signatureHeader \|\| !timestampHeader \|\| !signingSecret) return false;
25
26	// Replay protection: reject requests older than 5 minutes
27	const timestamp = parseInt(timestampHeader, 10);
28	if (Number.isNaN(timestamp)) return false;
29	if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 60 * 5) return false;
30
31	// Slack signs the literal string: "v0:" + timestamp + ":" + raw body
32	const basestring = `v0:${timestamp}:${rawBody}`;
33	const expected = 'v0=' + crypto
34	.createHmac('sha256', signingSecret)
35	.update(basestring, 'utf8')
36	.digest('hex');
37
38	try {
39	return crypto.timingSafeEqual(
40	Buffer.from(signatureHeader),
41	Buffer.from(expected)
42	);
43	} catch {
44	return false;
45	}
46	}
47	```
48
49	### Express Webhook Handler
50
51	```javascript
52	const express = require('express');
53	const app = express();
54
55	// CRITICAL: Use express.raw() - Slack signs the raw body, not parsed JSON
56	app.post('/webhooks/slack',
57	express.raw({ type: 'application/json' }),
58	(req, res) => {
59	const signature = req.headers['x-slack-signature'];
60	const timestamp = req.headers['x-slack-request-timestamp'];
61	const rawBody = req.body.toString('utf8');
62
63	if (!verifySlackRequest(rawBody, signature, timestamp, process.env.SLACK_SIGNING_SECRET)) {
64	return res.status(401).send('Invalid signature');
65	}
66
67	const payload = JSON.parse(rawBody);
68
69	// Handle the one-time url_verification challenge when configuring the endpoint
70	if (payload.type === 'url_verification') {
71	return res.status(200).json({ challenge: payload.challenge });
72	}
73
74	// Standard event_callback envelope
75	if (payload.type === 'event_callback') {
76	const event = payload.event;
77	switch (event.type) {
78	case 'app_mention':
79	console.log(`Mentioned by ${event.user} in ${event.channel}: ${event.text}`);
80	break;
81	case 'message':
82	console.log(`Message in ${event.channel}: ${event.text}`);
83	break;
84	case 'reaction_added':
85	console.log(`Reaction :${event.reaction}: added by ${event.user}`);
86	break;
87	case 'team_join':
88	console.log(`New team member: ${event.user.id}`);
89	break;
90	case 'app_home_opened':
91	console.log(`App home opened by ${event.user}`);
92	break;
93	default:
94	console.log(`Unhandled event: ${event.type}`);
95	}
96	}
97
98	// Respond within 3 seconds or Slack will retry
99	res.status(200).send('OK');
100	}
101	);
102	```
103
104	### Python Signature Verification (FastAPI)
105
106	```python
107	import hmac
108	import hashlib
109	import time
110
111	def verify_slack_request(raw_body: bytes, signature_header: str, timestamp_header: str, signing_secret: str) -> bool:
112	if not signature_header or not timestamp_header or not signing_secret:
113	return False
114
115	try:
116	timestamp = int(timestamp_header)
117	except ValueError:
118	return False
119
120	# Replay protection: reject requests older than 5 minutes
121	if abs(time.time() - timestamp) > 60 * 5:
122	return False
123
124	# Slack signs the literal string: "v0:" + timestamp + ":" + raw body
125	basestring = f"v0:{timestamp}:{raw_body.decode('utf-8')}".encode("utf-8")
126	expected = "v0=" + hmac.new(
127	signing_secret.encode("utf-8"),
128	basestring,
129	hashlib.sha256,
130	).hexdigest()
131
132	return hmac.compare_digest(expected, signature_header)
133	```
134
135	> For complete working examples with tests, see:
136	> - [examples/express/](examples/express/) - Full Express implementation
137	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
138	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
139
140	## Common Ev

People who liked this also viewed

6 picks

Type

slack-webhooks

80stars10forks

View on GitHub

How to install slack-webhooks?

hookdeck/webhook-skills/slack-webhooks

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Slack Webhooks
2
3	## When to Use This Skill
4
5	- Setting up a Slack Events API webhook handler (Request URL)
6	- Debugging `X-Slack-Signature` verification failures
7	- Handling the initial `url_verification` challenge from Slack
8	- Processing events like `app_mention`, `message`, `reaction_added`, `team_join`, or `app_home_opened`
9	- Returning a 2xx response within 3 seconds to avoid Slack retries
10
11	## Essential Code (USE THIS)
12
13	Slack signs every Events API request with HMAC-SHA256. The signed content is the
14	literal string `v0:{timestamp}:{raw_body}`, and the result is sent as
15	`X-Slack-Signature: v0=<hex>`. Use the raw request body — parsing JSON
16	before verifying will change byte ordering and break the signature.
17
18	### Slack Signature Verification (JavaScript)
19
20	```javascript
21	const crypto = require('crypto');
22
23	function verifySlackRequest(rawBody, signatureHeader, timestampHeader, signingSecret) {
24	if (!signatureHeader \|\| !timestampHeader \|\| !signingSecret) return false;
25
26	// Replay protection: reject requests older than 5 minutes
27	const timestamp = parseInt(timestampHeader, 10);
28	if (Number.isNaN(timestamp)) return false;
29	if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 60 * 5) return false;
30
31	// Slack signs the literal string: "v0:" + timestamp + ":" + raw body
32	const basestring = `v0:${timestamp}:${rawBody}`;
33	const expected = 'v0=' + crypto
34	.createHmac('sha256', signingSecret)
35	.update(basestring, 'utf8')
36	.digest('hex');
37
38	try {
39	return crypto.timingSafeEqual(
40	Buffer.from(signatureHeader),
41	Buffer.from(expected)
42	);
43	} catch {
44	return false;
45	}
46	}
47	```
48
49	### Express Webhook Handler
50
51	```javascript
52	const express = require('express');
53	const app = express();
54
55	// CRITICAL: Use express.raw() - Slack signs the raw body, not parsed JSON
56	app.post('/webhooks/slack',
57	express.raw({ type: 'application/json' }),
58	(req, res) => {
59	const signature = req.headers['x-slack-signature'];
60	const timestamp = req.headers['x-slack-request-timestamp'];
61	const rawBody = req.body.toString('utf8');
62
63	if (!verifySlackRequest(rawBody, signature, timestamp, process.env.SLACK_SIGNING_SECRET)) {
64	return res.status(401).send('Invalid signature');
65	}
66
67	const payload = JSON.parse(rawBody);
68
69	// Handle the one-time url_verification challenge when configuring the endpoint
70	if (payload.type === 'url_verification') {
71	return res.status(200).json({ challenge: payload.challenge });
72	}
73
74	// Standard event_callback envelope
75	if (payload.type === 'event_callback') {
76	const event = payload.event;
77	switch (event.type) {
78	case 'app_mention':
79	console.log(`Mentioned by ${event.user} in ${event.channel}: ${event.text}`);
80	break;
81	case 'message':
82	console.log(`Message in ${event.channel}: ${event.text}`);
83	break;
84	case 'reaction_added':
85	console.log(`Reaction :${event.reaction}: added by ${event.user}`);
86	break;
87	case 'team_join':
88	console.log(`New team member: ${event.user.id}`);
89	break;
90	case 'app_home_opened':
91	console.log(`App home opened by ${event.user}`);
92	break;
93	default:
94	console.log(`Unhandled event: ${event.type}`);
95	}
96	}
97
98	// Respond within 3 seconds or Slack will retry
99	res.status(200).send('OK');
100	}
101	);
102	```
103
104	### Python Signature Verification (FastAPI)
105
106	```python
107	import hmac
108	import hashlib
109	import time
110
111	def verify_slack_request(raw_body: bytes, signature_header: str, timestamp_header: str, signing_secret: str) -> bool:
112	if not signature_header or not timestamp_header or not signing_secret:
113	return False
114
115	try:
116	timestamp = int(timestamp_header)
117	except ValueError:
118	return False
119
120	# Replay protection: reject requests older than 5 minutes
121	if abs(time.time() - timestamp) > 60 * 5:
122	return False
123
124	# Slack signs the literal string: "v0:" + timestamp + ":" + raw body
125	basestring = f"v0:{timestamp}:{raw_body.decode('utf-8')}".encode("utf-8")
126	expected = "v0=" + hmac.new(
127	signing_secret.encode("utf-8"),
128	basestring,
129	hashlib.sha256,
130	).hexdigest()
131
132	return hmac.compare_digest(expected, signature_header)
133	```
134
135	> For complete working examples with tests, see:
136	> - [examples/express/](examples/express/) - Full Express implementation
137	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
138	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
139
140	## Common Ev

People who liked this also viewed

6 picks

Type