Skip to content

Readme.md

Latest commit

 

History

History
111 lines (79 loc) · 4.17 KB

Readme.md

File metadata and controls

111 lines (79 loc) · 4.17 KB
Raw

🪝 HookLens

A lightweight, self-hosted webhook gateway for African Fintech developers.

Status License TypeScript Next.js

📖 Overview

HookLens is a dedicated webhook infrastructure designed to receive, verify, and reliably process webhook events from major payment providers.

The goal of this project is to provide a unified, consistent interface for handling incoming webhooks while keeping provider-specific logic completely isolated. This makes it effortless to support additional providers in the future without muddying your core application logic.

Supported Providers:

  • 🇳🇬 Paystack
  • 🌍 Flutterwave
  • 🇳🇬 Monnify
  • (More coming soon)

✨ Features & Roadmap

✅ Phase 1: Webhook Endpoint

  • Receive incoming webhook requests
  • Parse request payloads securely
  • Basic request validation
  • Structured, modular project architecture

✅ Phase 2: Event Processing

  • Advanced event parsing
  • Automatic provider detection
  • Intelligent event routing
  • Modular service architecture

✅ Phase 3: Signature Verification

  • Provider-specific HMAC signature verification
  • Shared verification interface
  • Extensible verifier architecture
  • Constant-time signature comparison to mitigate timing attacks
  • Unit tests for verification logic

🚧 Phase 4: Delivery & Retry System (In Progress)

  • Webhook delivery management (BullMQ)
  • Automatic exponential backoff retry mechanism
  • Configurable retry policies
  • Failed event handling & dead-letter queues
  • Delivery status tracking

🚧 Phase 5: Dashboard & UI (In Progress)

  • Beautiful dark-mode Landing page
  • Built-in Waitlist collection
  • Webhook monitoring dashboard
  • Delivery history & payload inspection
  • Provider management interface
  • Project statistics and AI failure diagnostics

🏗️ Architecture

HookLens follows a highly modular architecture where each responsibility is isolated into its own pipeline component

Each payment provider implements its own verification logic while conforming to a shared TypeScript interface. This allows new providers to be added effortlessly with minimal changes to the core codebase.

🛡️ Security First

Processing webhooks involves sensitive financial data. HookLens is built with security as a primary focus:

  • Strict Signature Verification: All payloads are validated using the provider's official signing secrets.
  • Timing Attack Mitigation: Constant-time signature comparison (crypto.timingSafeEqual) is used exclusively.
  • Provider Isolation: Verification logic is strictly isolated per provider.
  • Pre-validation: Malformed or unsigned events are dropped before they ever reach the event processing queue.

🛠️ Tech Stack

  • Language: TypeScript
  • Backend: Node.js, Express
  • Frontend / Dashboard: Next.js (App Router), React 19, Tailwind CSS
  • Testing: Jest
  • Security: Node Native Crypto (HMAC Signature Verification)

🤔 Why build this?

Webhook systems power the modern internet, especially in fintech (payment processing, recurring billing, ledger updates).

This project is an exploration of the engineering challenges involved in building a production-oriented webhook platform, including:

  • Guaranteeing reliable event delivery in distributed systems.
  • Handling downstream server outages with smart retry mechanisms.
  • Normalizing disparate API shapes from multiple third-party providers.
  • Providing operational visibility through a clean, native dashboard.

📄 License

This project is available under the MIT License. Free to use, self-host, and modify forever.