Build a Webhook Receiver Service with Express and Signature Verification (Step by Step)

mkdir webhook-receiver
cd webhook-receiver
npm init -y
npm install express better-sqlite3 crypto dotenv ejs morgan
npm install -D nodemon

// db.js
const Database = require('better-sqlite3');
const path = require('path');

const db = new Database(path.join(__dirname, 'webhooks.db'));

db.exec(`
  CREATE TABLE IF NOT EXISTS webhooks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source TEXT NOT NULL,
    event TEXT NOT NULL,
    payload TEXT NOT NULL,
    signature TEXT,
    verified INTEGER DEFAULT 0,
    status TEXT DEFAULT 'received',
    retry_count INTEGER DEFAULT 0,
    headers TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    processed_at DATETIME
  );

  CREATE TABLE IF NOT EXISTS webhook_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    webhook_id INTEGER,
    action TEXT NOT NULL,
    message TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (webhook_id) REFERENCES webhooks(id)
  );

  CREATE INDEX IF NOT EXISTS idx_webhooks_status ON webhooks(status);
  CREATE INDEX IF NOT EXISTS idx_webhooks_created ON webhooks(created_at);
`);

module.exports = db;

// middleware/verifySignature.js
const crypto = require('crypto');

/**
 * Verify HMAC-SHA256 signature from the webhook source.
 * Expects source to provide the header name via options.
 */
function verifySignature({ secret, headerName = 'x-signature-256', encoding = 'sha256' } = {}) {
  return (req, res, next) => {
    const signature = req.headers[headerName.toLowerCase()];
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature header' });
    }

    const rawBody = req.body; // Must be raw/buffer body for verification

    const computed = crypto
      .createHmac(encoding, secret)
      .update(typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody))
      .digest('hex');

    // Timing-safe comparison prevents timing attacks
    const isValid = crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(computed)
    );

    if (!isValid) {
      req.webhookVerified = false;
      return res.status(403).json({ error: 'Invalid signature' });
    }

    req.webhookVerified = true;
    next();
  };
}

module.exports = verifySignature;

// routes/webhook.js
const express = require('express');
const router = express.Router();
const db = require('../db');
const verifySignature = require('../middleware/verifySignature');

// Stripe-style webhook endpoint
router.post('/stripe',
  express.raw({ type: 'application/json' }),
  verifySignature({
    secret: process.env.STRIPE_WEBHOOK_SECRET || 'whsec_test',
    headerName: 'stripe-signature',
  }),
  handleWebhook('stripe')
);

// GitHub-style webhook endpoint
router.post('/github',
  express.json(),
  verifySignature({
    secret: process.env.GITHUB_WEBHOOK_SECRET || 'ghp_test',
    headerName: 'x-hub-signature-256',
  }),
  handleWebhook('github')
);

// Generic webhook endpoint
router.post('/generic/:source',
  express.json(),
  handleWebhook('generic')
);

function handleWebhook(source) {
  return (req, res) => {
    const event = req.headers['x-event-name'] || req.headers['x-github-event'] || 'unknown';
    const payload = typeof req.body === 'object' ? JSON.stringify(req.body) : req.body.toString();
    const headers = JSON.stringify(req.headers);

    const stmt = db.prepare(`
      INSERT INTO webhooks (source, event, payload, signature, verified, headers, status)
      VALUES (?, ?, ?, ?, ?, ?, 'received')
    `);

    const result = stmt.run(
      source,
      event,
      payload,
      req.headers['stripe-signature'] || req.headers['x-hub-signature-256'] || null,
      req.webhookVerified ? 1 : 0,
      headers
    );

    // Log the reception
    db.prepare(`
      INSERT INTO webhook_logs (webhook_id, action, message)
      VALUES (?, 'received', 'Webhook received from ' || ?)
    `).run(result.lastInsertRowid, source);

    // Acknowledge immediately (webhook senders expect fast 200)
    res.status(200).json({ received: true, id: result.lastInsertRowid });

    // Process asynchronously
    processWebhookAsync(result.lastInsertRowid, source, event, payload);
  };
}

async function processWebhookAsync(id, source, event, payload) {
  try {
    // Simulate processing — replace with your business logic
    console.log(`Processing webhook ${id}: ${source}/${event}`);

    // Update status
    db.prepare(`UPDATE webhooks SET status = 'completed', processed_at = CURRENT_TIMESTAMP WHERE id = ?`).run(id);
    db.prepare(`INSERT INTO webhook_logs (webhook_id, action, message) VALUES (?, 'completed', 'Processed successfully')`).run(id);
  } catch (err) {
    handleProcessingError(id, err);
  }
}

// Retry failed webhooks with exponential backoff
const MAX_RETRIES = 5;
const BASE_DELAY = 1000; // 1 second

async function handleProcessingError(id, error) {
  const webhook = db.prepare('SELECT * FROM webhooks WHERE id = ?').get(id);
  if (!webhook) return;

  const retryCount = webhook.retry_count + 1;

  if (retryCount > MAX_RETRIES) {
    db.prepare(`UPDATE webhooks SET status = 'failed', retry_count = ? WHERE id = ?`).run(retryCount, id);
    db.prepare(`INSERT INTO webhook_logs (webhook_id, action, message) VALUES (?, 'failed', ?)`)
      .run(id, `Failed after ${MAX_RETRIES} retries: ${error.message}`);
    return;
  }

  const delay = BASE_DELAY * Math.pow(2, retryCount - 1); // 1s, 2s, 4s, 8s, 16s
  db.prepare(`UPDATE webhooks SET status = 'retrying', retry_count = ? WHERE id = ?`).run(retryCount, id);
  db.prepare(`INSERT INTO webhook_logs (webhook_id, action, message) VALUES (?, 'retry', ?)`)
    .run(id, `Retry ${retryCount}/${MAX_RETRIES} in ${delay}ms`);

  setTimeout(() => {
    processWebhookAsync(id, webhook.source, webhook.event, webhook.payload);
  }, delay);
}

// server.js
require('dotenv').config();
const express = require('express');
const morgan = require('morgan');
const path = require('path');

const app = express();
app.use(morgan('combined'));

// Raw body parsing for signature verification endpoints
app.use('/api/webhooks/stripe', express.raw({ type: '*/*' }));

// Standard JSON parsing for everything else
app.use(express.json());

// Routes
app.use('/api/webhooks', require('./routes/webhook'));
app.use('/dashboard', require('./routes/dashboard'));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Webhook receiver on port ${PORT}`));