@bernierllc/webhook-service

Complete webhook management service with receiving, validation, delivery, and monitoring.

Features

• Webhook Reception: Secure webhook endpoint with signature validation
• Provider Support: GitHub, Stripe, SendGrid, and custom webhooks
• Event Processing: Queue-based processing with retry logic
• Webhook Delivery: Reliable outbound webhook delivery
• Monitoring: Real-time webhook analytics and health monitoring
• Rate Limiting: Built-in rate limiting and DDoS protection

Installation

npm install @bernierllc/webhook-service

Quick Start

import { WebhookService } from '@bernierllc/webhook-service';

const webhookService = new WebhookService({
  receivers: [
    {
      source: 'github',
      secret: process.env.GITHUB_WEBHOOK_SECRET,
      events: ['push', 'pull_request'],
    },
    {
      source: 'stripe',
      secret: process.env.STRIPE_WEBHOOK_SECRET,
    },
  ],
  rateLimiting: {
    windowMs: 60000, // 1 minute
    maxRequests: 100,
  },
});

await webhookService.start();

Usage

Processing Incoming Webhooks

// In your HTTP handler
app.post('/webhooks/github', async (req, res) => {
  try {
    const event = await webhookService.processIncomingWebhook(
      'github',
      req.body,
      req.headers
    );

    res.status(200).json({ received: true, eventId: event.id });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

Creating Webhook Endpoints

const endpoint = await webhookService.createEndpoint({
  url: 'https://myapp.com/webhooks/github',
  events: ['push', 'pull_request'],
  secret: 'my-webhook-secret',
  filters: [
    {
      field: 'data.repository.name',
      operator: 'equals',
      value: 'my-important-repo',
    },
  ],
  retryPolicy: {
    maxAttempts: 3,
    initialDelayMs: 1000,
    backoffMultiplier: 2,
  },
});

Webhook Delivery

// Deliver webhook to endpoint
const delivery = await webhookService.deliverWebhook(endpoint, event);

// Retry failed delivery
await webhookService.retryDelivery(delivery.id);

Monitoring

// Get statistics
const stats = await webhookService.getStats({
  from: new Date(Date.now() - 24 * 60 * 60 * 1000),
  to: new Date(),
});

console.log(`Total events: ${stats.totalEvents}`);
console.log(`Success rate: ${stats.successfulDeliveries / stats.totalDeliveries * 100}%`);

// Check health
const health = await webhookService.getHealthStatus();
console.log(`Service healthy: ${health.healthy}`);

Supported Providers

GitHub

{
  source: 'github',
  secret: process.env.GITHUB_WEBHOOK_SECRET,
  events: ['push', 'pull_request', 'issues']
}

Stripe

{
  source: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET,
  apiVersion: '2020-08-27'
}

SendGrid

{
  source: 'sendgrid',
  events: ['delivered', 'opened', 'clicked']
}

Custom Webhooks

{
  source: 'custom',
  secret: 'your-secret',
  signatureHeader: 'x-custom-signature',
  algorithm: 'sha256'
}

API Reference

WebhookService

Constructor

new WebhookService(config: WebhookServiceConfig)

Methods

• start(): Start the webhook service
• stop(): Stop the webhook service
• processIncomingWebhook(source, payload, headers): Process an incoming webhook
• createEndpoint(request): Create a webhook endpoint
• updateEndpoint(id, updates): Update an endpoint
• deleteEndpoint(id): Delete an endpoint
• getEndpoint(id): Get endpoint by ID
• listEndpoints(filter?): List endpoints
• deliverWebhook(endpoint, event): Deliver a webhook
• retryDelivery(deliveryId): Retry a failed delivery
• getStats(timeframe?): Get webhook statistics
• getHealthStatus(): Get service health status
• simulateWebhook(endpointId, data): Test webhook delivery
• validateEndpoint(url): Validate endpoint URL

License

See LICENSE file for details.