Open-source webhook infrastructure for receiving, inspecting, delivering, retrying, and replaying webhooks.
HookTrace gives developers a self-hostable place to see what happens to their webhooks — from the moment an event arrives to the moment it reaches your application.
Built for developers who need more visibility and control than a simple webhook endpoint provides.
Webhooks are simple until something goes wrong.
A provider sends an event.
Your application doesn't receive it.
Or it receives it twice.
Or your endpoint returns 500.
Or a downstream service is temporarily unavailable.
Or you need to understand exactly what payload was sent three hours ago.
HookTrace provides the infrastructure and visibility around those events.
- Receive webhooks through managed routes
- Inspect webhook payloads and headers
- Track delivery status
- Retry failed deliveries
- Replay events
- Send events to configurable delivery targets
- Monitor webhook activity
- Stream events to the dashboard in real time
- Run webhook tunnels during local development
- Connect integrations
- Monitor system metrics with Prometheus
- Self-host the entire stack
HookTrace is built as a small set of services that work together:
┌──────────────────┐
│ Webhook Provider │
│ Stripe / GitHub │
│ Razorpay / etc. │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ HookTrace API │
│ FastAPI │
└────────┬─────────┘
│
┌────────┴─────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │
│ Events │ │ Queues │
│ Routes │ │ Pub/Sub │
└─────────────┘ └──────┬──────┘
│
▼
┌────────────────┐
│ Worker Service │
│ Delivery/Retry │
└───────┬────────┘
│
▼
┌─────────────────┐
│ Your Application│
└─────────────────┘
▲
│
┌──────┴───────┐
│ Next.js │
│ Dashboard │
└──────────────┘
| Component | Technology | Purpose |
|---|---|---|
| API | FastAPI | HTTP API and webhook ingestion |
| Dashboard | Next.js | Event and infrastructure UI |
| Database | PostgreSQL | Persistent application and event data |
| Queue / PubSub | Redis | Background processing and realtime updates |
| Worker | Python | Delivery, retries and background jobs |
| Tunnels | Python | Local webhook development |
| Metrics | Prometheus | Application metrics |
Create routes that receive webhook requests from external services.
HookTrace records the relevant event information so you can inspect and process it asynchronously.
Inspect:
- Request payloads
- Headers
- Provider
- Event type
- Delivery status
- Attempt count
- Errors
- Timestamps
Configure delivery targets and forward incoming events to your application.
Failed deliveries can be retried according to the configured retry behavior.
This helps protect your integration from temporary downstream failures.
Replay previously received events when you need to test an endpoint, recover from a failure, or reproduce an integration problem.
HookTrace uses WebSockets and Redis Pub/Sub to provide real-time event updates to the dashboard.
Events that cannot successfully complete delivery can be surfaced as failed/dead-letter events for investigation and recovery.
Use HookTrace tunnels to expose local development endpoints to webhook providers without deploying your application first.
HookTrace is designed to work with webhook-producing services and provides an integration layer for provider-specific functionality.
HookTrace exposes Prometheus metrics so you can monitor the webhook infrastructure alongside the rest of your stack.
Before running HookTrace locally, install:
- Git
- Docker
- Docker Compose
- Node.js
- Python
PostgreSQL and Redis can be run through the provided Docker setup.
git clone https://github.com/hooktracehq/hooktrace.git
cd hooktraceCreate your local environment configuration from the example file:
cp .env.example .envThen configure the required values.
Important: Never commit real credentials, API keys, OAuth secrets, database passwords, or production tokens to the repository.
docker compose up -dFrom the project root:
cd servicesInstall the Python dependencies:
pip install -r requirements.txtStart the FastAPI application:
uvicorn api.main:app --reloadThe API should now be available at:
http://localhost:8000
In another terminal:
cd web
npm install
npm run devThe dashboard will be available at:
http://localhost:3000
The basic HookTrace flow is:
Provider
│
▼
HookTrace Route
│
├── Store event
│
├── Queue delivery
│
▼
Worker
│
▼
Your endpoint
Create a route in the dashboard, then configure your webhook provider to send events to the generated HookTrace endpoint.
Once an event arrives, you can inspect it from the dashboard and follow its delivery lifecycle.
For a complete walkthrough, see:
HookTrace is designed to run on infrastructure you control.
You can self-host the complete stack using Docker and the project's deployment configuration.
Common deployment targets include:
- Docker
- Railway
- Render
- Kubernetes
- Your own VPS or cloud infrastructure
See the deployment documentation:
hooktrace/
│
├── services/
│ ├── api/ # FastAPI application
│ ├── worker/ # Background delivery workers
│ ├── tunnels/ # Local development tunnels
│ ├── cli/ # CLI tooling
│ └── shared/ # Shared service code
│
├── web/ # Next.js dashboard
│
├── docs/ # Documentation
│
├── .github/ # CI and contribution templates
│
├── docker-compose.yml
├── LICENSE
└── README.md
HookTrace is actively developed and welcomes contributions.
If you're interested in working on the project:
- Fork the repository.
- Create a branch.
- Make your changes.
- Run the relevant tests and checks.
- Open a pull request.
See:
The project is evolving toward a complete open-source webhook infrastructure platform.
Areas of development include:
- Webhook ingestion
- Event inspection
- Delivery targets
- Retry processing
- Event replay
- Real-time dashboard updates
- Local development tunnels
- Prometheus metrics
- Integration system
- More provider integrations
- Improved deployment experience
- Expanded CLI functionality
- More comprehensive documentation
- Additional observability features
The roadmap is subject to change as the project develops.
There are many ways to contribute:
- Report bugs
- Improve documentation
- Add integrations
- Improve the dashboard
- Improve delivery reliability
- Add tests
- Improve deployment tooling
- Suggest features
- Submit pull requests
Please read the contribution guidelines before opening a pull request.
If you discover a security vulnerability, please avoid opening a public issue with sensitive details.
See the project's security policy for responsible disclosure instructions.
HookTrace is open source and licensed under the Apache License 2.0.
See LICENSE for the complete license text.
HookTrace exists to make webhook infrastructure easier to understand, debug, and operate.
Receive. Inspect. Deliver. Retry. Replay.
Self-host it, modify it, and build on top of it.