[Feature Request] Add framework adapters for Express, Fastify, and Nest.js

[JosephDoUrden]

[Feature Request] Add framework adapters for Express, Fastify, and Nest.js

Summary

Add framework-specific middleware/adapters to simplify webhook verification in popular Node.js frameworks. This would reduce boilerplate and make adoption easier for developers.

Motivation

Currently, users need to manually:

• Parse headers (x-webhook-signature, x-webhook-timestamp, x-webhook-nonce)
• Extract raw body
• Handle errors and map to HTTP status codes
• Set up nonce validators

This is shown in the Express.js example, but it's repetitive boilerplate that could be abstracted.

Proposed Solution

Create framework-specific adapters:

1. Express.js Middleware

import { webhookVerifier } from 'webhook-hmac-kit/express';

app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  webhookVerifier({
    secret: process.env.WEBHOOK_SECRET!,
    tolerance: 300,
    nonceValidator: async (nonce) => { /* ... */ }
  }),
  (req, res) => {
    // req.webhookVerified === true
    const event = JSON.parse(req.body.toString('utf-8'));
    res.sendStatus(200);
  }
);

2. Fastify Plugin

import { webhookPlugin } from 'webhook-hmac-kit/fastify';

fastify.register(webhookPlugin, {
  secret: process.env.WEBHOOK_SECRET!,
  tolerance: 300,
});

fastify.post('/webhook', {
  preHandler: fastify.verifyWebhook,
}, async (request, reply) => {
  // request.webhookVerified === true
  return { received: true };
});

3. Nest.js Guard/Interceptor

import { WebhookGuard } from 'webhook-hmac-kit/nest';

@Post('/webhook')
@UseGuards(WebhookGuard)
async handleWebhook(@Body() body: Buffer, @Headers() headers) {
  // Guard automatically verifies
  return { received: true };
}

Design Considerations

• Zero dependencies: Adapters should only depend on framework types (e.g., @types/express)
• Type safety: Full TypeScript support with proper request augmentation
• Error handling: Automatic HTTP status code mapping:
  • WebhookSignatureError → 401 Unauthorized
  • WebhookTimestampError → 400 Bad Request
  • WebhookNonceError → 409 Conflict
• Flexibility: Allow custom header names, error handlers, and nonce validators
• Raw body requirement: Adapters must ensure raw body is available (not parsed JSON)

Implementation Plan

1. Express middleware (src/adapters/express.ts)

   • Middleware factory function
   • Request type augmentation
   • Error handling middleware

2. Fastify plugin (src/adapters/fastify.ts)

   • Fastify plugin pattern
   • Decorator for request object
   • Hook integration

3. Nest.js guard (src/adapters/nest.ts)

   • CanActivate guard implementation
   • Decorator for metadata
   • Exception filters for error handling

4. Documentation

   • Update README with adapter examples
   • Add framework-specific guides
   • Migration guide from manual implementation