I Built a Stripe-Grade Webhook Delivery System for NestJS (Open Source)

Your Service
    │
    │  webhookSenderService.send({ url, payload, secret })
    ▼
┌──────────────────────────┐
│      BullMQ Queue        │  ← persisted in Redis, survives restarts
└──────────────────────────┘
    │
    │  Worker picks up job
    ▼
┌──────────────────────────┐
│  Signs payload (HMAC)    │
│  POSTs via axios         │
│  Checks response status  │
└──────────────────────────┘
    │
    ├── 2xx      → ✅ Logged as success
    ├── 5xx/429  → 🔁 Retried with backoff (up to 6 attempts)
    └── 4xx/410  → ☠️  Dead-letter queue immediately

npm install nestjs-webhook-sender bullmq ioredis

// app.module.ts
import { WebhookSenderModule } from 'nestjs-webhook-sender';

@Module({
  imports: [
    WebhookSenderModule.register({
      redis: { host: 'localhost', port: 6379 },
    }),
  ],
})
export class AppModule {}

@Injectable()
export class OrderService {
  constructor(private readonly webhooks: WebhookSenderService) {}

  async onOrderCompleted(order: Order) {
    const webhookId = await this.webhooks.send({
      url: customer.webhookUrl,
      event: 'order.completed',
      payload: {
        orderId: order.id,
        total: order.total,
        completedAt: new Date().toISOString(),
      },
      secret: customer.webhookSecret,
      signingStyle: 'standard', // or 'stripe' or 'github'
    });

    // store webhookId for delivery log lookups
  }
}

webhook-id: wh_01HXYZ...
webhook-timestamp: 1715000000
webhook-signature: v1,base64encodedhmac

stripe-signature: t=1715000000,v1=hexencodedhmac

x-hub-signature-256: sha256=hexencodedhmac

// 5xx, 429, network errors → retry (transient failure)
// 400, 401, 403, 404      → DLQ immediately (permanent failure, no point retrying)
// 410 Gone                → DLQ immediately (endpoint intentionally disabled)

// Inspect a failed webhook
const entry = await this.webhooks.getDlqEntry(webhookId);
// {
//   webhookId: 'wh_01HXYZ...',
//   url: 'https://...',
//   payload: { ... },
//   reason: 'HTTP 404 Not Found',
//   failedAt: '2024-01-15T10:30:00.000Z'
// }

// After the customer fixes their endpoint — replay it
await this.webhooks.replay(webhookId);
// Re-enqueues with fresh attempt count

const deliveries = await this.webhooks.listDeliveries(webhookId);
// [
//   { attemptNumber: 1, status: 'failed', statusCode: 503, timestamp: '...' },
//   { attemptNumber: 2, status: 'success', statusCode: 200, timestamp: '...' }
// ]

@Get('webhooks/:id/deliveries')
getDeliveries(@Param('id') id: string) {
  return this.webhooks.listDeliveries(id);
}

@Post('webhooks/:id/replay')
replay(@Param('id') id: string) {
  return this.webhooks.replay(id);
}

import { WebhookSigner } from 'nestjs-webhook-sender';

@Post('webhooks/orders')
receiveOrder(@Req() req: Request, @Headers() headers: Record<string, string>) {
  const isValid = WebhookSigner.verifyStandard({
    webhookId: headers['webhook-id'],
    timestamp: headers['webhook-timestamp'],
    signature: headers['webhook-signature'],
    rawBody: JSON.stringify(req.body),
    secret: process.env.WEBHOOK_SECRET,
  });

  if (!isValid) throw new UnauthorizedException('Invalid signature');

  // process verified event...
}

test/webhook-sender.signer.spec.ts     — 20 tests (all 3 signing styles)
test/webhook-sender.processor.spec.ts  — 19 tests (HTTP delivery with nock mocking)
test/webhook-sender.service.spec.ts    — 18 tests (BullMQ mocked)

nock('https://example.com').post('/webhook').reply(503); // simulate server error
await expect(processor.process(job, dlqQueue)).rejects.toThrow('status 503');
// BullMQ will retry this job automatically

WebhookSenderModule.registerAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    redis: {
      host: config.get('REDIS_HOST'),
      port: config.get<number>('REDIS_PORT'),
      password: config.get('REDIS_PASSWORD'),
    },
    defaultSecret: config.get('WEBHOOK_SECRET'),
  }),
})