Simple. Reliable. Self-hosted.
Built for indie hackers and startups who need webhook debugging without the enterprise price tag.
Features • Quick Start • Deployment • Documentation • Contributing
- Instant Webhook Relay - Create public endpoints in seconds, no configuration needed
- Smart Retries - Exponential backoff with configurable policies and circuit breaking
- Real-time Debugging - Event logs, request/response inspection, and manual replay
- Beautiful Dashboard - Modern, dark-mode UI built with Next.js and Tailwind CSS
- Easy Self-Hosting - Docker Compose, Kubernetes, Railway, and Render support
- Persistent Storage - PostgreSQL for reliability, Redis for queuing
- Async Workers - Background job processing with horizontal scaling
- Signature Validation - HMAC signing for webhook security
- Audit Logs - Complete event history and tracking
- Dead Letter Queue - Never lose failed events, replay them anytime
- Local Forwarding - Test webhooks locally without ngrok
- Provider Templates - Pre-built configs for Stripe, GitHub, Razorpay, and more
- Idempotency Support - Prevent duplicate event processing
- Event Routing - Forward to HTTP endpoints (more targets planned)
Get up and running in under 60 seconds:
git clone https://github.com/Yasir761/hooktrace.git
cd hooktrace
cp .env.example .env
docker-compose upThat's it! Open http://localhost:3000 and start relaying webhooks.
Deploy the full stack to managed platforms:
|
Railway API + Worker + DB + Redis |
Render Full Stack Deployment |
Vercel Dashboard Only |
Note: Vercel deploys the dashboard only. Deploy API + Worker on Railway/Render or self-host.
| Component | Minimum Version |
|---|---|
| Docker | 20.10+ |
| Docker Compose | 2.0+ |
| PostgreSQL | 14+ |
| Redis | 7+ |
| Python (dev only) | 3.9+ |
| Node.js (dev only) | 18+ |
┌─────────────────┐
│ Dashboard │ Next.js + Tailwind
│ (Port 3000) │ Real-time UI
└────────┬────────┘
│
│ HTTP
▼
┌─────────────────┐
│ API Server │ FastAPI (Python)
│ (Port 3001) │ Webhook ingestion & routing
└────────┬────────┘
│
│ Enqueue jobs
▼
┌─────────────────┐ ┌──────────────┐
│ Redis Queue │◄──────│ PostgreSQL │
│ │ │ Database │
└────────┬────────┘ └──────────────┘
│
│ Process jobs
▼
┌─────────────────┐
│ Async Worker │ Python (Redis-backed worker)
│ │ Retry logic & delivery
└─────────────────┘
hooktrace/
├── services/
│ ├── api/ # FastAPI backend
│ └── worker/ # Python job processor
├── web/ # Next.js dashboard
├── docker-compose.yml # Local development stack
└── .github/ # CI/CD workflows
# Clone the repository
git clone https://github.com/hooktracehq/hooktrace.git
cd hooktrace
# Copy environment file
cp .env.example .env
# Start development stack
docker-compose upTest webhooks without exposing your machine:
# Start local receiver
python -m http.server 3000
# Configure Hooktrace destination URL based on your setup:When running Hooktrace in Docker:
http://host.docker.internal:3000
When running Hooktrace locally (without Docker):
http://localhost:3000
Note: Use
host.docker.internalwhen Hooktrace runs inside Docker to reach your host machine. Uselocalhostwhen running Hooktrace natively.
No ngrok or tunneling required!
Environment variables (see .env.example):
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/hooktrace
REDIS_URL=redis://localhost:6379
# API Server
API_PORT=3001
API_HOST=0.0.0.0
# Dashboard
NEXT_PUBLIC_API_URL=http://localhost:3001
DASHBOARD_PORT=3000
# Webhook Behavior
WEBHOOK_MAX_RETRY_ATTEMPTS=3
WEBHOOK_DEFAULT_TIMEOUT=30For production deployments, see DEPLOYMENT.md.
- Public relay endpoints
- Event persistence & queuing
- Async worker with retries
- Basic dashboard with logs
- Docker Compose setup
- Dead Letter Queue
- Manual replay support
- Idempotency key support
- HMAC signature validation
- Audit logs
- WebSocket live updates
- Prometheus metrics
- Webhook provider templates
- Local dev forwarding (no ngrok needed)
- Multiple delivery targets (HTTP, SQS, Kafka, Redis)
- Event aggregation mode
- AI-powered failure analysis
- Replay comparison view
- Advanced routing rules
- Auto-scaling optimization
- Helm chart for Kubernetes
- Terraform modules
- SaaS deployment option
- Deployment Guide - Production deployment options
- API Reference - REST API documentation
- Contributing Guide - How to contribute
- FAQ - Common questions
We love contributions! Whether it's bug fixes, new features, or documentation improvements.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please read CONTRIBUTING.md for detailed guidelines.
Licensed under the Apache License 2.0.
This means you can use Hooktrace for commercial purposes, modify it, distribute it, and use it privately. Just include the license and copyright notice.
- Documentation: hooktrace.dev/docs
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Hooktrace stands on the shoulders of giants. Inspired by:
Built with modern webhook best practices and a focus on developer experience.
Built with ❤️ by developer, for developers
⭐ Star us on GitHub — it helps!