Self-Hosting

Run Hookdrop on your own infrastructure

You can run Hookdrop on your own servers. Self-hosting gives you full control over your data and infrastructure.

Self-hosting requires familiarity with Node.js, PostgreSQL, and Redis. If you want to get started quickly, the cloud-hosted version at hookdrop.dev requires no setup.

Requirements

• Node.js v20+
• PostgreSQL 16+
• Redis 7+

Setup

1. Clone the repository

   Clone the repo and install dependencies:

   git clone https://github.com/bobprince4u/hookdrop.git && cd hookdrop && npm install
   
2. Configure environment variables

   Copy the example environment file:

   cp .env.example .env
   

   Open .env and fill in your values. See .env.example in the repository for the full list of required variables. Key settings include:

   DATABASE_URL=postgresql://postgres:password@localhost:5432/hookdrop
   REDIS_URL=redis://localhost:6379
   JWT_SECRET=your-long-random-secret
   
3. Run database migrations

   Apply the database schema:

   npm run migrate:up
   
4. Start all services

   Open four terminal windows and run one command in each:

   # Terminal 1 — Ingestion API
   npm run dev:ingestion
   

   # Terminal 2 — Delivery Worker
   npm run dev:worker
   

   # Terminal 3 — Dashboard API
   npm run dev:api
   

   # Terminal 4 — Frontend
   npm run dev:web
   

Architecture overview

Hookdrop is composed of four services that run independently:

• Ingestion API (port 3002) — Receives incoming webhooks from providers like Stripe, GitHub, and Shopify. This is the URL you configure in your webhook provider settings.
• Delivery Worker — Picks up queued jobs from Redis and forwards events to your configured destinations. Handles retries with exponential backoff.
• Dashboard API (port 3003) — Powers the web dashboard. Handles authentication, endpoint management, event queries, and billing.
• Frontend (port 3004) — The web UI. Connects to the Dashboard API and streams live events via WebSocket.

The Ingestion API and Dashboard API are intentionally separate. Under heavy webhook load, you can scale the Ingestion API independently without affecting the dashboard.

Docker Compose support is coming soon. A single docker-compose.yml for one-command self-hosting is on the roadmap.