∿ hookdash

Zero-config, self-hosted webhook gateway with a beautiful dashboard.

Receive, queue, retry, and monitor webhooks — no Redis, no Postgres, just SQLite.

Quick Start · Configuration · Dashboard · API · Docker · Contributing

Why hookdash?

Every app that integrates with Stripe, GitHub, Twilio, or Shopify needs to handle webhooks. But webhooks are fragile — your server goes down, you lose events. You need retry logic, signature verification, monitoring, and replay capabilities.

hookdash gives you all of that in a single command:

npx hookdash start

No Redis. No Postgres. No Kafka. Just a single SQLite file and a beautiful dashboard.

How it compares

| Feature | hookdash | Svix | Convoy | Hookdeck | |---|---|---|---|---| | Zero external deps | ✅ SQLite only | ❌ PG + Redis + Kafka | ❌ PG + Redis | ❌ Cloud only | | Setup time | npx hookdash | Hours | Hours | Minutes | | Self-hosted | ✅ | ✅ | ✅ | ❌ | | Dashboard | ✅ Beautiful | ✅ | ✅ | ✅ | | Signature verification | ✅ Multi-provider | ✅ | ✅ | ✅ | | License | MIT | MIT (server) | Varies | Proprietary | | Target audience | Devs & small teams | Enterprise | Enterprise | Everyone |

✨ Features

• 🪝 Webhook Ingestion — Receive webhooks from any service at /webhook/:source
• 🔐 Signature Verification — Built-in support for Stripe, GitHub, Twilio, Shopify, and generic HMAC
• 🔄 Smart Retries — Exponential backoff with jitter, configurable per-endpoint
• ⚡ Circuit Breaker — Auto-disable failing endpoints, probe for recovery
• 💀 Dead Letter Queue — Events that exceed retries are preserved for inspection
• 🔁 One-Click Replay — Re-deliver any failed event from the dashboard
• 📊 Real-time Dashboard — Beautiful dark UI with live event stream
• 📡 Server-Sent Events — Real-time updates without WebSocket complexity
• 🗄️ SQLite Storage — Zero-config, single file, fast, reliable
• 🐳 Docker Ready — Single container deployment
• ⚙️ YAML Config — Simple configuration with environment variable interpolation

🚀 Quick Start

Option 1: npx (quickest)

# Create a config file
npx hookdash init

# Edit hookdash.config.yml with your settings, then:
npx hookdash start

Option 2: Install globally

npm install -g hookdash
hookdash init
hookdash start

Option 3: Docker

docker run -p 9090:9090 -v hookdash-data:/app/data me-npm/hookdash

Test it works

# Send a test webhook
curl -X POST http://localhost:9090/webhook/my-service \
  -H "Content-Type: application/json" \
  -d '{"event": "test.event", "data": {"hello": "world"}}'

# Open the dashboard
open http://localhost:9090

📋 Configuration

Create a hookdash.config.yml in your project root:

server:
  port: 9090
  host: 0.0.0.0

database:
  path: ./hookdash.db

delivery:
  poll_interval: 1000        # ms between delivery polls
  default_timeout: 30000     # ms per delivery attempt
  default_max_retries: 8     # retries before dead letter

sources:
  # Stripe
  - name: stripe
    provider: stripe
    signing_secret: ${STRIPE_WEBHOOK_SECRET}
    endpoints:
      - url: http://localhost:3000/api/webhooks/stripe
        events: ["payment_intent.*", "charge.*"]

  # GitHub
  - name: github
    provider: github
    signing_secret: ${GITHUB_WEBHOOK_SECRET}
    endpoints:
      - url: http://localhost:3000/api/webhooks/github

  # Generic HMAC-SHA256
  - name: my-service
    provider: generic
    signing_secret: my-secret-key
    endpoints:
      - url: http://localhost:3000/hooks

Environment Variables

Use ${ENV_VAR} syntax in your config to reference environment variables:

signing_secret: ${STRIPE_WEBHOOK_SECRET}

CLI Options

hookdash start [options]

Options:
  -p, --port <port>    Server port (overrides config)
  -h, --host <host>    Server host (overrides config)
  -c, --config <path>  Path to config file
  -d, --db <path>      Database file path

📊 Dashboard

The dashboard is available at http://localhost:9090 and provides:

• Event Explorer — Search and filter all incoming webhooks
• Event Detail — View full payload, headers, and delivery timeline
• Replay — One-click re-delivery of any event
• Stats — Success rates, event volume, top sources
• Endpoint Manager — Configure and test forwarding destinations
• Real-time Updates — Live event stream via SSE

📡 API Reference

All API endpoints are available at /api/.

Events

| Method | Endpoint | Description | |---|---|---| | GET | /api/events | List events (paginated) | | GET | /api/events/:id | Event detail + deliveries | | POST | /api/events/:id/replay | Replay an event | | DELETE | /api/events/:id | Delete an event |

Query parameters for GET /api/events:

| Param | Type | Description | |---|---|---| | page | number | Page number (default: 1) | | per_page | number | Items per page (default: 20, max: 100) | | source | string | Filter by source name | | status | string | Filter by delivery status | | event_type | string | Filter by event type | | from | string | ISO date, events after | | to | string | ISO date, events before | | search | string | Search in event body |

Endpoints

| Method | Endpoint | Description | |---|---|---| | GET | /api/endpoints | List endpoints | | POST | /api/endpoints | Create endpoint | | PUT | /api/endpoints/:id | Update endpoint | | DELETE | /api/endpoints/:id | Delete endpoint | | POST | /api/endpoints/:id/test | Test endpoint connectivity |

Stats & Health

| Method | Endpoint | Description | |---|---|---| | GET | /api/stats | Aggregate statistics | | GET | /api/stream | SSE real-time event stream | | GET | /api/health | Health check |

🪝 Webhook Providers

Stripe

- name: stripe
  provider: stripe
  signing_secret: ${STRIPE_WEBHOOK_SECRET}

Verifies using the Stripe-Signature header with HMAC-SHA256. Validates timestamp tolerance (5 minutes).

GitHub

- name: github
  provider: github
  signing_secret: ${GITHUB_WEBHOOK_SECRET}

Verifies using the X-Hub-Signature-256 header with HMAC-SHA256.

Twilio

- name: twilio
  provider: twilio
  signing_secret: ${TWILIO_AUTH_TOKEN}

Verifies using the X-Twilio-Signature header with HMAC-SHA1.

Shopify

- name: shopify
  provider: shopify
  signing_secret: ${SHOPIFY_WEBHOOK_SECRET}

Verifies using the X-Shopify-Hmac-Sha256 header with HMAC-SHA256 (Base64).

Generic HMAC

- name: my-service
  provider: generic
  signing_secret: my-secret-key

Verifies using X-Webhook-Signature or X-Signature header with HMAC-SHA256.

🔄 Retry Strategy

hookdash uses exponential backoff with jitter:

| Attempt | Delay (approx) | |---|---| | 1 | ~1s | | 2 | ~2s | | 3 | ~4s | | 4 | ~8s | | 5 | ~16s | | 6 | ~32s | | 7 | ~1 min | | 8 | ~2 min |

After the configured max retries (default: 8), the event moves to the dead letter queue and can be replayed manually from the dashboard.

Circuit Breaker

If an endpoint fails 5 times consecutively, hookdash opens the circuit and stops sending to that endpoint for 60 seconds. After the cooldown, it enters half-open state and probes with a single request.

🐳 Docker

Using Docker Compose

# Clone the repo
git clone https://github.com/me-npm/hookdash.git
cd hookdash

# Create your config
cp hookdash.config.example.yml hookdash.config.yml

# Start
docker compose up -d

Using Docker directly

docker build -t hookdash .
docker run -p 9090:9090 -v hookdash-data:/app/data hookdash

🛠 Development

# Clone
git clone https://github.com/me-npm/hookdash.git
cd hookdash

# Install dependencies
npm install
cd dashboard && npm install && cd ..

# Start in dev mode (with hot reload)
npm run dev

# Run tests
npm test

# Build for production
npm run build

🗺 Roadmap

• [ ] Web UI for creating sources (no YAML editing)
• [ ] Webhook forwarding transforms (modify payload before delivery)
• [ ] Rate limiting per source
• [ ] Authentication for dashboard (API key / basic auth)
• [ ] Metrics export (Prometheus)
• [ ] Webhook playground (send test events from dashboard)
• [ ] Plugin system for custom providers
• [ ] PostgreSQL adapter for high-volume deployments

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT — see LICENSE for details.

Built with ❤️ for developers who are tired of losing webhooks.

⭐ Star on GitHub · 🐛 Report Bug · 💡 Request Feature