Skip to content

Commit 4313d03

Browse files
kermakerma
committed
feat: add echo server with webhook signature verification
1 parent e5a2704 commit 4313d03

File tree

7 files changed

+571
-0
lines changed

7 files changed

+571
-0
lines changed

‎apps/webhook-verifier/.gitignore‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
2+
3+
# Logs
4+
5+
logs
6+
_.log
7+
npm-debug.log_
8+
yarn-debug.log*
9+
yarn-error.log*
10+
lerna-debug.log*
11+
.pnpm-debug.log*
12+
13+
# Caches
14+
15+
.cache
16+
17+
# Diagnostic reports (https://nodejs.org/api/report.html)
18+
19+
report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
20+
21+
# Runtime data
22+
23+
pids
24+
_.pid
25+
_.seed
26+
*.pid.lock
27+
28+
# Directory for instrumented libs generated by jscoverage/JSCover
29+
30+
lib-cov
31+
32+
# Coverage directory used by tools like istanbul
33+
34+
coverage
35+
*.lcov
36+
37+
# nyc test coverage
38+
39+
.nyc_output
40+
41+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
42+
43+
.grunt
44+
45+
# Bower dependency directory (https://bower.io/)
46+
47+
bower_components
48+
49+
# node-waf configuration
50+
51+
.lock-wscript
52+
53+
# Compiled binary addons (https://nodejs.org/api/addons.html)
54+
55+
build/Release
56+
57+
# Dependency directories
58+
59+
node_modules/
60+
jspm_packages/
61+
62+
# Snowpack dependency directory (https://snowpack.dev/)
63+
64+
web_modules/
65+
66+
# TypeScript cache
67+
68+
*.tsbuildinfo
69+
70+
# Optional npm cache directory
71+
72+
.npm
73+
74+
# Optional eslint cache
75+
76+
.eslintcache
77+
78+
# Optional stylelint cache
79+
80+
.stylelintcache
81+
82+
# Microbundle cache
83+
84+
.rpt2_cache/
85+
.rts2_cache_cjs/
86+
.rts2_cache_es/
87+
.rts2_cache_umd/
88+
89+
# Optional REPL history
90+
91+
.node_repl_history
92+
93+
# Output of 'npm pack'
94+
95+
*.tgz
96+
97+
# Yarn Integrity file
98+
99+
.yarn-integrity
100+
101+
# dotenv environment variable files
102+
103+
.env
104+
.env.development.local
105+
.env.test.local
106+
.env.production.local
107+
.env.local
108+
109+
# parcel-bundler cache (https://parceljs.org/)
110+
111+
.parcel-cache
112+
113+
# Next.js build output
114+
115+
.next
116+
out
117+
118+
# Nuxt.js build / generate output
119+
120+
.nuxt
121+
dist
122+
123+
# Gatsby files
124+
125+
# Comment in the public line in if your project uses Gatsby and not Next.js
126+
127+
# https://nextjs.org/blog/next-9-1#public-directory-support
128+
129+
# public
130+
131+
# vuepress build output
132+
133+
.vuepress/dist
134+
135+
# vuepress v2.x temp and cache directory
136+
137+
.temp
138+
139+
# Docusaurus cache and generated files
140+
141+
.docusaurus
142+
143+
# Serverless directories
144+
145+
.serverless/
146+
147+
# FuseBox cache
148+
149+
.fusebox/
150+
151+
# DynamoDB Local files
152+
153+
.dynamodb/
154+
155+
# TernJS port file
156+
157+
.tern-port
158+
159+
# Stores VSCode versions used for testing VSCode extensions
160+
161+
.vscode-test
162+
163+
# yarn v2
164+
165+
.yarn/cache
166+
.yarn/unplugged
167+
.yarn/build-state.yml
168+
.yarn/install-state.gz
169+
.pnp.*
170+
171+
# IntelliJ based IDEs
172+
.idea
173+
174+
# Finder (MacOS) folder config
175+
.DS_Store

‎apps/webhook-verifier/README.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Webhook Echo Server with Signature Verification
2+
3+
A minimal HTTP server that echoes back the body of POST requests and verifies webhook signatures.
4+
5+
## Features
6+
7+
- Simple HTTP server built with Bun
8+
- Echoes back the body of any POST request
9+
- Verifies webhook signatures using HMAC-SHA256
10+
- Returns verification status in the response
11+
12+
## Installation
13+
14+
To install dependencies:
15+
16+
```bash
17+
bun install
18+
```
19+
20+
## Usage
21+
22+
### Running the server
23+
24+
Start the server:
25+
26+
```bash
27+
bun run server.ts
28+
```
29+
30+
The server will be available at http://localhost:1337.
31+
32+
### Making requests
33+
34+
You can test the server with curl:
35+
36+
```bash
37+
# Send a POST request with a JSON body (without signature verification)
38+
curl -X POST -H "Content-Type: application/json" -d '{"message":"Hello World"}' http://localhost:3000
39+
40+
# Send a POST request with webhook signature verification
41+
curl -X POST \
42+
-H "Content-Type: application/json" \
43+
-H "webhook-id: 3f3d820e-d01c-4c56-8be4-b20053225679" \
44+
-H "webhook-timestamp: 1745118540" \
45+
-H "webhook-signature: v1,4gOAiajJT7ah++XpDFdRyK/TJ75whRjUcKOWnvsHNlk=" \
46+
-d '{"type":"subscription.created","timestamp":"2024-08-09T12:44:04.777884Z"}' \
47+
http://localhost:3000
48+
```
49+
50+
### Webhook Signature Verification
51+
52+
The server verifies webhook signatures using the following formula:
53+
54+
```
55+
envelope = webhook-id.webhook-timestamp.payload
56+
signature = base64Encode(HMAC-SHA256(envelope, secret))
57+
webhook-signature = v1,signature
58+
```
59+
60+
Required headers for verification:
61+
- `webhook-id`: A unique identifier for the webhook
62+
- `webhook-timestamp`: A Unix timestamp
63+
- `webhook-signature`: The signature in the format `v1,{base64_signature}`
64+
65+
If all headers are present, the server will verify the signature using the secret key defined in the environment variable `WEBHOOK_SECRET` or the default one hardcoded in the server.
66+
67+
Example:
68+
- webhook-id: `3f3d820e-d01c-4c56-8be4-b20053225679`
69+
- webhook-timestamp: `1745118540`
70+
- payload: `{"type":"subscription.created","timestamp":"2024-08-09T12:44:04.777884Z"}`
71+
- secret: `whsec_mUt3nH+3wx/djdHf8RHn9yJMMiAhq10b`
72+
- webhook-signature: `v1,4gOAiajJT7ah++XpDFdRyK/TJ75whRjUcKOWnvsHNlk=`
73+
74+
### Response Format
75+
76+
The server responds with a JSON object containing:
77+
- `body`: The original request body
78+
- `signature_verification`: Object containing verification status
79+
- `status`: String indicating verification status ("Valid", "Invalid", "Missing required headers", or "Not verified")
80+
- `valid`: Boolean indicating if the signature is valid
81+
82+
Example response for a valid signature:
83+
```json
84+
{
85+
"body": "{\"type\":\"subscription.created\",\"timestamp\":\"2024-08-09T12:44:04.777884Z\"}",
86+
"signature_verification": {
87+
"status": "Valid",
88+
"valid": true
89+
}
90+
}
91+
```
92+
93+
Example response for an invalid signature:
94+
```json
95+
{
96+
"body": "{\"type\":\"subscription.created\",\"timestamp\":\"2024-08-09T12:44:04.777884Z\"}",
97+
"signature_verification": {
98+
"status": "Invalid",
99+
"valid": false
100+
}
101+
}
102+
```
103+
104+
## Environment Variables
105+
106+
- `WEBHOOK_SECRET`: The secret key used for signature verification (default: `whsec_mUt3nH+3wx/djdHf8RHn9yJMMiAhq10b`)
107+
108+
## Development
109+
110+
This project was created using Bun, a fast all-in-one JavaScript runtime.

‎apps/webhook-verifier/bun.lockb‎

3.38 KB
Binary file not shown.

‎apps/webhook-verifier/package.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "webhook-verifier",
3+
"module": "server.ts",
4+
"type": "module",
5+
"scripts": {
6+
"start": "bun run server.ts",
7+
"test": "bun run test-signature.ts"
8+
},
9+
"devDependencies": {
10+
"@types/bun": "latest"
11+
},
12+
"peerDependencies": {
13+
"typescript": "^5.0.0"
14+
}
15+
}

0 commit comments

Comments
 (0)