@hookinbox/verify
Zero-dependency webhook signature verification for Stripe, GitHub, Shopify, and more.
Most platform SDKs validate signatures but throw generic errors like:
"Invalid signature"
This library returns structured failure reasons (timestamp too old, body modified, wrong algorithm, etc.) to make debugging easier.
const result = verifyStripe(...)
if (!result.ok) {
console.log(result.kind)
}
// "timestamp_too_old"
// "signature_mismatch"
// "missing_header"
if (!result.ok) {
console.log(result.kind)
}
// "timestamp_too_old"
// "signature_mismatch"
// "missing_header"
Why @hookinbox/verify?
Why use this instead of platform SDKs?
- Zero dependencies - No bloat, just verification
- Detailed diagnostics - Know exactly why verification failed
- Type-safe - Full TypeScript support
- Multi-platform - One package for all platforms
- Well-tested - 80%+ code coverage
- Lightweight - < 5KB minified
Common issues we help debug:
- Timestamp too old/future (with exact age)
- Wrong secret key used
- Body modified by middleware
- SHA-1 vs SHA-256 confusion
- Base64 encoding issues
Installation
npm install @hookinbox/verify
Usage
Stripe
import { verifyStripe } from '@hookinbox/verify';
const result = verifyStripe({
rawBodyBytes: rawBody, // string | Buffer | Uint8Array
stripeSignatureHeader: req.headers['stripe-signature'],
signingSecret: 'whsec_...', // must start with whsec_
toleranceSec: 300, // optional, default 300
});
if (result.ok) {
console.log(' Valid signature');
console.log('Timestamp:', result.timestamp);
console.log('Age:', result.ageSec, 'seconds');
} else {
console.error(' Error:', result.kind);
if (result.kind === 'timestamp_too_old') {
console.error(`Timestamp is ${result.ageSec}s old (max: ${result.toleranceSec}s)`);
}
if (result.kind === 'signature_mismatch') {
console.error('Expected:', result.expectedHex);
console.error('Received:', result.receivedV1);
}
}
const result = verifyStripe({
rawBodyBytes: rawBody, // string | Buffer | Uint8Array
stripeSignatureHeader: req.headers['stripe-signature'],
signingSecret: 'whsec_...', // must start with whsec_
toleranceSec: 300, // optional, default 300
});
if (result.ok) {
console.log(' Valid signature');
console.log('Timestamp:', result.timestamp);
console.log('Age:', result.ageSec, 'seconds');
} else {
console.error(' Error:', result.kind);
if (result.kind === 'timestamp_too_old') {
console.error(`Timestamp is ${result.ageSec}s old (max: ${result.toleranceSec}s)`);
}
if (result.kind === 'signature_mismatch') {
console.error('Expected:', result.expectedHex);
console.error('Received:', result.receivedV1);
}
}
GitHub
import { verifyGitHub } from '@hookinbox/verify';
const result = verifyGitHub({
rawBodyBytes: rawBody,
signature256: req.headers['x-hub-signature-256'], // preferred
signature: req.headers['x-hub-signature'], // fallback (sha1)
secret: 'your-secret',
});
if (result.ok) {
console.log(' Valid signature');
console.log('Algorithm:', result.algorithm);
} else {
console.error(' Error:', result.kind);
}
const result = verifyGitHub({
rawBodyBytes: rawBody,
signature256: req.headers['x-hub-signature-256'], // preferred
signature: req.headers['x-hub-signature'], // fallback (sha1)
secret: 'your-secret',
});
if (result.ok) {
console.log(' Valid signature');
console.log('Algorithm:', result.algorithm);
} else {
console.error(' Error:', result.kind);
}
Shopify
import { verifyShopify } from '@hookinbox/verify';
const result = verifyShopify({
rawBodyBytes: rawBody,
hmacHeader: req.headers['x-shopify-hmac-sha256'],
secret: 'your-secret',
});
if (result.ok) {
console.log(' Valid signature');
} else {
console.error(' Error:', result.kind);
}
const result = verifyShopify({
rawBodyBytes: rawBody,
hmacHeader: req.headers['x-shopify-hmac-sha256'],
secret: 'your-secret',
});
if (result.ok) {
console.log(' Valid signature');
} else {
console.error(' Error:', result.kind);
}
Utilities
The package also exports timing-safe comparison utilities:
Timing-Safe String Comparison
import { timingSafeEqual } from '@hookinbox/verify';
const isValid = timingSafeEqual(expectedSignature, receivedSignature);
const isValid = timingSafeEqual(expectedSignature, receivedSignature);
Timing-Safe Byte Comparison
import { constantTimeEqual } from '@hookinbox/verify';
const a = new Uint8Array([1, 2, 3]);
const b = new Uint8Array([1, 2, 3]);
const isEqual = constantTimeEqual(a, b); // true
const a = new Uint8Array([1, 2, 3]);
const b = new Uint8Array([1, 2, 3]);
const isEqual = constantTimeEqual(a, b); // true
Hex Utilities
import { hexToBytes, bytesToHex } from '@hookinbox/verify';
// Convert hex string to bytes
const bytes = hexToBytes('deadbeef');
// Uint8Array([0xDE, 0xAD, 0xBE, 0xEF])
// Convert bytes to hex string
const hex = bytesToHex(bytes);
// 'deadbeef'
// Convert hex string to bytes
const bytes = hexToBytes('deadbeef');
// Uint8Array([0xDE, 0xAD, 0xBE, 0xEF])
// Convert bytes to hex string
const hex = bytesToHex(bytes);
// 'deadbeef'
Security
All signature comparisons use constant-time comparison to prevent timing attacks. This means the comparison time doesn't leak information about how many characters match.
Why this matters:
- Standard
===comparison short-circuits on first mismatch - Attackers can measure response times to guess secrets
- Our
timingSafeEqualalways compares all bytes
Features
- Zero dependencies
- TypeScript support
- Detailed error messages
- Timing-safe comparisons
- Works in Node.js, Edge, Cloudflare Workers
Development
Running Tests
# Run all tests
npm test
# Run in watch mode
npm run test:watch
# Check coverage
npm run test:coverage
npm test
# Run in watch mode
npm run test:watch
# Check coverage
npm run test:coverage
Building
npm run build
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Looking for ideas? Check out platforms we'd love to support:
- Clerk, Resend, Discord, Twilio, SendGrid
- Lemon Squeezy, Paddle, Chargebee
- Vercel, Railway, Linear
Testing
Comprehensive test suite with 80%+ coverage:
- Valid signature verification
- Invalid signature detection
- Edge cases (empty body, special chars, etc.)
- Timing-safe comparisons
- Platform-specific rules
License
MIT (c) HookInbox
Related
- HookInbox - Debug webhooks with live capture & verification
- Contributing Guide - Help us add more platforms!
Maintained by the HookInbox project.