⚡ WebHook Hub

An edge-first, open-source Webhooks-as-a-Service (WaaS) platform built on Cloudflare serverless stack.

WebHook Hub is a high-performance event delivery pipeline built to leverage the capabilities of Cloudflare's serverless edge. It provides developers with a robust, cost-effective pipeline for webhook ingestion and delivery—running entirely on Workers, D1, and KV with a focus on reliability, efficiency, and zero infrastructure overhead.

---

🏗️ High-Level Architecture

graph TD
    subgraph "Client Layer"
        A["Publisher Backend<br/>(SaaS Application)"]
        B["Developer Dashboard<br/>(React SPA)"]
    end

    subgraph "Cloudflare Edge (300+ PoPs)"
        C["API Worker<br/>(itty-router)"]
        D["Cron Scheduler<br/>(Every 1 min)"]
    end

    subgraph "Storage Layer"
        E[("D1 Database<br/>(SQLite)")]
        F[("Workers KV<br/>(Cache)")]
    end

    subgraph "Delivery Pipeline"
        G["Delivery Engine"]
        H["Transform & Sign"]
        I["Target Endpoints"]
    end

    A -->|"POST /api/v1/events<br/>API Key Auth"| C
    B -->|"REST API<br/>Google OAuth JWT"| C
    C -->|"Read/Write"| E
    C -->|"Cache Lookup"| F
    D -->|"Trigger"| G
    G -->|"Query Pending"| E
    G -->|"Rate Check"| F
    G --> H
    H -->|"HMAC-SHA256 Signed POST"| I
    I -->|"Delivery Logs"| E

Loading

---

✨ Core Features

Feature	Description
Edge-Native Ingestion	Built on Cloudflare Workers for sub-millisecond event ingestion with zero cold starts
Resilient Retry Pipeline	Exponential backoff (60s → 300s → 900s → 3600s) with Poison Event Isolation
Zero-Downtime Secret Rotation	Rolling webhook secrets (current + previous) for safe, uninterrupted rotations
Payload Transformations	In-transit JSON modifications (rename, remove, insert, template nesting) and event type filters
D1 Distributed Locks	Atomic SQLite-based concurrency control preventing double-delivery
Multi-Tenant Isolation	Strict logical isolation using SHA-256 hashed API Keys and JWT HS256 tokens
Google OAuth SSO	Passwordless authentication via Google Sign-In — no email/password attack surface
IP-Based Rate Limiting	Brute-force protection on auth routes (5 req/min) and global API rate limiting (60 req/min)
Dynamic CORS	Origin whitelisting for dashboard APIs; wildcard only for public event ingestion
RBAC & Team Management	Role-based access control with owner, admin, and member roles per organization
Developer Portal	Full React dashboard for endpoints, deliveries, audit logs, metrics, and team management

---

🔐 Authentication Flow

WebHook Hub uses passwordless Google OAuth for all dashboard user authentication. No passwords are stored or transmitted.

sequenceDiagram
    participant User as Developer
    participant Dashboard as React Dashboard
    participant Google as Google OAuth
    participant Worker as API Worker
    participant DB as D1 Database

    User->>Dashboard: Click "Sign in with Google"
    Dashboard->>Google: Request OAuth Credential
    Google-->>Dashboard: Return ID Token
    Dashboard->>Worker: POST /api/v1/auth/google {credential}
    Worker->>Google: Verify token via tokeninfo API
    Google-->>Worker: Return verified email & claims

    alt User Exists
        Worker->>DB: Lookup user by email
        DB-->>Worker: Return user record
    else New User
        Worker->>Worker: IP-based signup rate limit check
        Worker->>DB: Create user (auto-approved)
        Worker->>DB: Bootstrap org, project & API key
    end

    Worker->>Worker: Sign JWT (HS256)
    Worker-->>Dashboard: Return {token, user}
    Dashboard->>Dashboard: Store JWT in localStorage

Loading

---

🔄 Webhook Delivery Pipeline

flowchart TD
    A["Publisher POSTs Event"] --> B["API Worker Ingests"]
    B --> C["Store in D1<br/>status = pending"]
    C --> D["Return 201 Created"]

    E["⏰ Cron Trigger<br/>(Every 1 min)"] --> F["Query Deliverable Events"]
    F --> G{"Rate Limit<br/>Check (KV)"}
    G -->|"Limited"| H["Defer to<br/>Next Cycle"]
    G -->|"OK"| I["Acquire D1<br/>Atomic Lock"]
    I -->|"Lock Failed"| J["Skip<br/>(Already Processing)"]
    I -->|"Lock OK"| K["Apply Filters<br/>& Transforms"]
    K --> L["Sign Payload<br/>(HMAC-SHA256)"]
    L --> M["POST to Target URL"]
    M --> N{"Response?"}
    N -->|"2xx"| O["✅ Mark Delivered"]
    N -->|"Non-2xx"| P{"Retries Left?"}
    P -->|"Yes"| Q["Schedule Retry<br/>(Exponential Backoff)"]
    P -->|"Max Reached"| R["☠️ Mark Dead/Poisoned"]

    style A fill:#4CAF50,color:#fff
    style O fill:#4CAF50,color:#fff
    style R fill:#f44336,color:#fff

Loading

---

📁 Project Structure

webhook-platform/
├── apps/
│   ├── api-worker/          # Cloudflare Worker — REST API, jobs, middleware
│   │   ├── src/
│   │   │   ├── routes/      # Auth, webhooks, events, deliveries, admin, docs
│   │   │   ├── services/    # Delivery, rate-limit, transform, version, workspace
│   │   │   ├── middleware/  # JWT & API Key authentication
│   │   │   ├── jobs/        # Scheduled delivery & retention cron jobs
│   │   │   └── db/          # Drizzle ORM schema & migrations
│   │   └── wrangler.jsonc   # Worker configuration
│   └── dashboard/           # React SPA — Vite + React Router
│       ├── src/
│       │   ├── pages/       # Landing, Login, Dashboard, Settings, etc.
│       │   ├── layouts/     # Main layout with header & sidebar
│       │   └── lib/         # API client, auth context, utilities
│       └── index.html       # Entry point with OG metadata
├── docs/                    # Comprehensive technical documentation
├── terraform/               # IaC for Cloudflare resource provisioning
└── README.md

---

🚀 Quick Start

Prerequisites

• Node.js v18+
• Git
• Wrangler CLI (npm install -g wrangler)

1. Clone & Install

git clone https://github.com/MasirJafri1/webhook-platform.git
cd webhook-platform

# Backend
cd apps/api-worker && npm install

# Frontend
cd ../dashboard && npm install

2. Initialize Local Database

cd apps/api-worker
npx wrangler d1 migrations apply webhook-platform-db --local

3. Launch Dev Servers

# Terminal 1: API Worker
cd apps/api-worker
npm run dev
# → http://localhost:8787

# Terminal 2: Dashboard
cd apps/dashboard
npm run dev
# → http://localhost:5173

4. Sign In

Open http://localhost:5173 and click "Sign in with Google". The platform auto-provisions your workspace (organization, project, and API key) on first login.

---

🔒 Security Hardening

WebHook Hub implements defense-in-depth security:

Layer	Implementation
Authentication	Passwordless Google OAuth SSO — zero password attack surface
JWT Signing	HS256 with secret stored in Cloudflare Wrangler Secrets (never in code/env files)
API Keys	SHA-256 hashed at rest — plaintext never stored in D1
CORS	Dynamic origin whitelisting for dashboard APIs; wildcard only for /api/v1/events
Rate Limiting	IP-based: 5 req/min on auth, 60 req/min global, per-endpoint egress throttling
Signup Protection	5 new accounts per IP per 3 hours
Transport	HTTPS/TLS 1.3 enforced via Cloudflare Edge
SQL Injection	Parameterized queries via Drizzle ORM
Replay Protection	HMAC signature timestamps with drift detection + idempotency keys
Circuit Breaker	Auto-disable endpoints after 20 consecutive delivery failures

graph LR
    subgraph "Perimeter"
        A["Cloudflare Edge<br/>TLS 1.3"]
    end

    subgraph "Auth Layer"
        B["Google OAuth<br/>Token Verification"]
        C["JWT HS256<br/>(Wrangler Secret)"]
        D["API Key<br/>SHA-256 Hash"]
    end

    subgraph "Protection"
        E["IP Rate Limiting"]
        F["Dynamic CORS"]
        G["Drizzle ORM<br/>(Parameterized SQL)"]
    end

    A --> B & D
    B --> C
    C --> E
    D --> E
    E --> F
    F --> G

Loading

---

📖 Documentation

WebHook Hub includes comprehensive technical documentation covering every aspect of the platform:

Introduction & Core Concepts

• Platform Overview — Feature sets, value propositions, and comparative benefits
• System Architecture — Edge-first topology, core layers, and storage design
• Core Concepts — Domain vocabulary: publishers, events, deliveries, retries

Getting Started

• Quick Start Guide — End-to-end local setup with Google OAuth
• Local Development — Mock files, seeding, and local testing
• Deployment Manual — CI/CD and manual Cloudflare deployment
• Infrastructure as Code — Terraform configuration for Cloudflare resources

API Reference

• Authentication — Google OAuth, API Key validation, and JWT sessions
• Webhooks API — CRUD for webhook endpoint targets
• Events API — Event publishing and querying
• Deliveries API — Delivery attempt history and logs
• Metrics API — Live latencies, totals, and response status counts
• Error Responses — Standard error formats (400–500)

Advanced Guides

• Secret Rotation — Zero-downtime signing key rotations
• Retry Policy — Exponential backoff schedule and poison checks
• Filtering & Transformations — Event routing and JSON templates

Security & Isolation

• Webhook Signatures — HMAC-SHA256 verification (Node.js, Python, Go)
• API Key Protection — Zero-plaintext SHA-256 hash lookups
• Replay Protection — Timestamp drift limits and idempotency
• Security Model — Multi-tenant isolation, CORS, rate limiting, and OAuth

Operations & Maintenance

• Monitoring & Metrics — Observability and audit logs
• Rate Limits — Ingress, egress, and auth rate limiting
• Data Retention — 7-day storage limits and purging
• Dead Letter Queue — Quarantining failed/poisoned events
• Disaster Recovery — D1 restoration and failover

Internal Architecture

• Delivery Engine — Pipeline routing mechanics
• Retry Engine — Concurrency handling for delayed retries
• Concurrency & Locking — D1-based distributed event locking
• Database Schema — Table representations and indexing
• Tenancy & Scoping — Multi-tenant isolation and OAuth context resolution

---

🛠️ Tech Stack

Layer	Technology
Runtime	Cloudflare Workers (V8 Isolates)
Database	Cloudflare D1 (Distributed SQLite)
Cache	Cloudflare Workers KV
ORM	Drizzle ORM
API Router	itty-router
Frontend	React + Vite + React Router
Auth	Google OAuth 2.0 (GSI) + JWT HS256
IaC	Terraform (Cloudflare Provider)
CI/CD	GitHub Actions

---

👤 Author

Built by Masir Jafri — Software Engineer specializing in Full-Stack Development, Backend System Design, and Generative AI.

🌐 Website	masirjafri.in
📝 Blog	blog.masirjafri.in
💻 GitHub	@MasirJafri1
🔗 LinkedIn	linkedin.com/in/masirjafri

---

📄 License

This project is open-source. See LICENSE for details.