DEV Community: Saifuddin Tipu

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

Saifuddin Tipu — Fri, 08 May 2026 08:23:40 +0000

Every SaaS app eventually needs to send webhooks. And every team eventually learns the hard way that "just HTTP POST it" isn't enough.

I've seen it go wrong the same way every time:

A customer's endpoint is down at 2am. The webhook fires once, gets a 503, and silently disappears.
A developer hardcodes the same signing secret for every customer. One leak exposes all of them.
Support opens a ticket: "We never received the payment webhook." Nobody can prove whether it was sent, what the response was, or whether it should be retried.

So I built nestjs-webhook-sender — a production-ready NestJS module that handles all of this properly.

What it does

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

The retry schedule is inspired by Svix (the webhook infrastructure company):

Attempt	Delay
1	Immediate
2	~5 seconds
3	~5 minutes
4	~30 minutes
5	~2 hours
6	~5 hours → DLQ

Each delay has ±20% jitter to prevent thundering herd when multiple webhooks fail at the same time.

Installation

npm install nestjs-webhook-sender bullmq ioredis

Setup (5 lines)

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

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

Sending a webhook

@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
  }
}

The webhook is non-blocking — it's enqueued immediately and processed by a background worker. Your API response isn't delayed.

Three signing styles

This was actually one of the trickier design decisions. Different consumers expect different signature formats:

Standard Webhooks spec (default)

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

Follows the Standard Webhooks spec. Good default for new systems.

Stripe-style

stripe-signature: t=1715000000,v1=hexencodedhmac

Use this if your customers already have Stripe SDK webhook verification set up — it's drop-in compatible.

GitHub-style

x-hub-signature-256: sha256=hexencodedhmac

Use this for integrations with GitHub Apps or any system expecting GitHub-format signatures.

All three use HMAC-SHA256 with crypto.timingSafeEqual for constant-time comparison (no timing attacks).

Smart retry logic

Not all failures are equal. The module routes them differently:

// 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)

This matters a lot in practice. If a customer deletes their endpoint, you don't want to burn through 6 retry attempts over 5 hours — you want to know immediately.

Dead-letter queue + replay

When a webhook exhausts all retries, it goes to the DLQ:

// 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

This is what makes support tickets answerable. "Did the webhook get sent?" → yes, here are the 6 delivery attempts. "Can you resend it?" → yes, one line of code.

Delivery logs

Every attempt (success or failure) is logged to Redis with a 7-day TTL:

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

You can surface this directly in a customer dashboard:

@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);
}

Signature verification (consumer side)

On the receiving end, the module exports a WebhookSigner.verifyStandard() helper:

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...
}

Testing

The package ships with 57 tests across three suites:

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)

The processor tests use nock to mock HTTP responses — no real server needed:

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

Async configuration with ConfigService

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'),
  }),
})

Why not just use Svix or Hookdeck?

Those are great services — but they're external infrastructure with a SaaS pricing model. If you want:

No external dependency — everything runs in your own Redis
Full control over retry logic, signing, and storage
No per-event pricing — send 10 or 10 million, same cost
Native NestJS DI — inject the service anywhere, mock it in tests

...then a library makes more sense.

Real-Time User Presence in NestJS — Multi-Tab, Multi-Instance, Zero Ghost Users

Saifuddin Tipu — Fri, 08 May 2026 03:51:30 +0000

"Is this user online?" sounds like a simple question. Until you actually try to answer it reliably.

I've worked on apps where the presence indicator was basically decorative — it showed "online" for users who had closed the tab 10 minutes ago. It showed "offline" for users who had three tabs open and just closed one. It worked fine on a single server and completely broke when we scaled horizontally.

So I built nestjs-socket-presence — a NestJS module that gets presence right.

The problems it solves

Problem 1: Multi-tab users

A user opens your app in 3 tabs. They close tab 1. Are they offline?

No — they still have 2 active connections. But a naive implementation marks them offline the moment any socket disconnects.

nestjs-socket-presence tracks a SET of socket IDs per user in Redis. The user only goes offline when the last socket is removed.

presence:user:{userId}:sockets  →  SET { socketId1, socketId2, socketId3 }

Close one tab → 2 remaining → still online.

Close all tabs → SET is empty → offline event fires.

Problem 2: Ghost users (ungraceful disconnects)

A user's laptop dies. No disconnect event fires. They stay "online" forever.

The fix: Redis TTL + heartbeat. Every user key expires after 2 × ttl seconds unless the client sends a heartbeat.

// Client — keep presence alive
setInterval(() => {
  socket.emit('presence:heartbeat', { userId: 'user-123' });
}, 15_000); // every 15s when ttl=30

No heartbeat = key expires = user goes offline automatically. No cron jobs, no cleanup workers.

Problem 3: Horizontal scaling

Two NestJS instances, same Redis. A user connects to instance A. A query on instance B asks if they're online.

Because all state lives in Redis (not in-process memory), any instance can answer any presence query. Zero coordination needed.

Instance A ──────┐
                 │  both read/write to
Instance B ──────┤  the same Redis keys
                 │
             Redis ← single source of truth

Installation

npm install nestjs-socket-presence ioredis

Setup

// app.module.ts
import { PresenceModule } from 'nestjs-socket-presence';

@Module({
  imports: [
    PresenceModule.register({
      redis: { host: 'localhost', port: 6379 },
      ttl: 30, // seconds — users go offline after 30s without heartbeat
    }),
  ],
})
export class AppModule {}

That's the entire setup. The module auto-registers a Socket.IO gateway that handles connect/disconnect/heartbeat/rooms.

Connect from the browser

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000', {
  auth: { userId: 'user-123' }, // presence tracked automatically on connect
});

// Heartbeat to prevent ghost-user TTL expiry
setInterval(() => {
  socket.emit('presence:heartbeat', { userId: 'user-123' });
}, 15_000);

On connect → presence:online broadcast fires.

On disconnect (last socket) → presence:offline broadcast fires.

No heartbeat for 30s → key expires → effectively offline.

Querying presence

Inject PresenceService anywhere:

import { PresenceService } from 'nestjs-socket-presence';

@Injectable()
export class ChatService {
  constructor(private readonly presence: PresenceService) {}

  // Single user
  async isAgentAvailable(agentId: string): Promise<boolean> {
    return this.presence.isOnline(agentId);
  }

  // Full presence object (includes socketIds, lastSeen, metadata)
  async getUserStatus(userId: string) {
    return this.presence.getUserPresence(userId);
    // → { userId, online, socketIds, lastSeen, metadata? }
  }

  // Bulk check — one Redis round-trip for hundreds of users
  async getTeamStatus(userIds: string[]) {
    return this.presence.getBulkPresence(userIds);
    // → Map<string, boolean>
  }
}

Room presence

Track who is online in a specific room — useful for collaborative features:

// Client joins a document room
socket.emit('presence:room:join', { userId: 'user-123', room: 'doc:abc' });

// Server queries who's in the room
const roomState = await this.presence.getRoomPresence('doc:abc');
// → { room: 'doc:abc', users: [UserPresence, ...], onlineCount: 4 }

Custom metadata

Pass arbitrary data when a user comes online — useful for routing, labeling, or filtering:

// From your own gateway or auth interceptor
await this.presenceService.setOnline(userId, socket.id, {
  role: 'support-agent',
  region: 'us-east',
  tier: 'premium',
});

// Read it back in a query
const presence = await this.presenceService.getUserPresence(userId);
console.log(presence?.metadata);
// → { role: 'support-agent', region: 'us-east', tier: 'premium' }

This makes it possible to build things like "route this chat to the nearest online premium agent."

Events reference

Client → Server

Event	Payload	When to use
`presence:identify`	`{ userId, metadata? }`	If userId wasn't in socket auth
`presence:heartbeat`	`{ userId }`	Every `ttl/2` seconds
`presence:room:join`	`{ userId, room }`	Enter a collaborative space
`presence:room:leave`	`{ userId, room }`	Exit a collaborative space

Server → Client (broadcast to all)

Event	Payload
`presence:online`	`{ userId, socketId }`
`presence:offline`	`{ userId, socketId }`
`presence:room:join`	`{ userId, room }`
`presence:room:leave`	`{ userId, room }`

Real-world use case: Customer support routing

@Injectable()
export class TicketRouter {
  constructor(private readonly presence: PresenceService) {}

  async assignTicket(ticket: Ticket): Promise<string | null> {
    const agents = await this.getAgentsForDepartment(ticket.department);
    const presenceMap = await this.presence.getBulkPresence(
      agents.map(a => a.userId)
    );

    const onlineAgents = agents.filter(a => presenceMap.get(a.userId));
    if (onlineAgents.length === 0) return null;

    // Pick least-busy online agent
    return onlineAgents.sort((a, b) => a.activeTickets - b.activeTickets)[0].userId;
  }
}

No polling. No stale cache. The answer is always current because it reads directly from Redis.

How it stores data in Redis

presence:user:{userId}          HASH   → { userId, online, lastSeen, metadata? }
presence:user:{userId}:sockets  SET    → { socketId1, socketId2, ... }
presence:socket:{socketId}      STRING → userId
presence:room:{room}            SET    → { userId1, userId2, ... }

All user keys have a TTL of 2 × ttl seconds. Heartbeat refreshes the TTL on every pulse.

Async configuration

PresenceModule.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'),
    },
    ttl: 30,
  }),
})

Tests

The package ships with 22 tests using an in-memory Redis mock — no real Redis required for unit tests:

npm test
# PASS  test/presence.service.spec.ts (22 tests)

The test suite covers:

Single and multi-socket user flows
TTL expiry edge cases
Room join/leave/cleanup
Bulk presence queries
Metadata persistence
Ghost user prevention (socket removed without explicit offline)

Why not Socket.IO rooms for presence?

Socket.IO rooms are in-process. They don't survive restarts and don't work across multiple server instances without the Redis adapter — and even then, querying "who is in this room" isn't straightforward.

nestjs-socket-presence stores everything in Redis explicitly, so:

Any instance can query any user's presence
Data survives server restarts (within TTL)
You can query presence from non-WebSocket code (HTTP handlers, cron jobs, etc.)

DEV Community: Saifuddin Tipu

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

What it does

Installation

Setup (5 lines)

Sending a webhook

Three signing styles

Standard Webhooks spec (default)

Stripe-style

GitHub-style

Smart retry logic

Dead-letter queue + replay

Delivery logs

Signature verification (consumer side)

Testing

Async configuration with ConfigService

Why not just use Svix or Hookdeck?

Links

Real-Time User Presence in NestJS — Multi-Tab, Multi-Instance, Zero Ghost Users

The problems it solves

Problem 1: Multi-tab users

Problem 2: Ghost users (ungraceful disconnects)

Problem 3: Horizontal scaling

Installation

Setup

Connect from the browser

Querying presence

Room presence

Custom metadata

Events reference

Client → Server

Server → Client (broadcast to all)

Real-world use case: Customer support routing

How it stores data in Redis

Async configuration

Tests

Why not Socket.IO rooms for presence?

Links