DHOOK #

Webhook Relay Service & CLI Tool

Forward webhooks from the cloud to your local development environment in real-time

What is DHOOK? #

DHOOK is a lightweight, self-hosted webhook relay service designed for developers. When building applications that integrate with external services like GitHub, Stripe, PayMe, or Telegram, you often need to receive webhooks during development. The problem is that these services require a publicly accessible URL, but your local development machine typically sits behind a NAT or firewall.

DHOOK solves this by acting as a relay between the internet and your local machine. You deploy the DHOOK server on any VPS or cloud server with a public IP, then run the DHOOK client on your local machine. The client connects to the server via WebSocket and receives all incoming webhooks in real-time, forwarding them to your local application. This allows you to develop and test webhook integrations without exposing your machine to the internet or paying for tunneling services.

🚀 Quick Start #

Installation #

# Install globally via pub.flutter-io.cn
dart pub global activate dhook

# Or install from source
dart pub global activate --source git https://github.com/alisheraxmedov/dhook.git

1. Deploy on Your Server #

# SSH to your server
ssh user@your-server.com

# Clone repository
git clone https://github.com/alisheraxmedov/dhook.git
cd dhook

# Run with Docker
docker-compose up -d

2. CLI Agent (on your machine) #

# Run the client
dhook client \
  --server wss://your-server.com/ws/my-channel \
  --target http://localhost:8000

3. Configure Your Webhook #

Point your webhook to:

https://your-server.com/webhook/my-channel

🔐 Authentication #

DHOOK uses API key authentication by default to secure your channels.

Create API Key #

# First, start the server
dhook server --port 3000

# Create API key for your channel
curl -X POST https://your-server.com/api/keys \
  -H "Content-Type: application/json" \
  -d '{"channel": "my-channel", "name": "production"}'

# Response:
# {"api_key": "dhk_xxx...", "channel": "my-channel", ...}

Connect with API Key #

dhook client \
  --server wss://your-server.com/ws/my-channel \
  --target http://localhost:8000 \
  --api-key dhk_xxx...

Disable Auth (Local Development Only) #

# ⚠️ NOT recommended for production!
dhook server --port 3000 --no-auth

🐳 Docker Deployment #

# Build and run
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop
docker-compose down

🛠️ Usage #

Server Commands #

# Start relay server on default port 3000
dhook server

# Start on custom port
dhook server --port 8080

# Start with API key authentication
dhook server --port 3000 --auth

Client Commands #

# Connect to relay and forward to localhost
dhook client \
  --server wss://your-server.com/ws/my-channel \
  --target http://localhost:8000

# With API key authentication
dhook client \
  --server wss://your-server.com/ws/my-channel \
  --target http://localhost:8000 \
  --api-key dhk_your_api_key

API Endpoints #

📦 Programmatic Usage #

import 'package:dhook/dhook.dart';

// Start a relay server
final server = RelayServer(port: 3000);
await server.start();

// Start with authentication
final authServer = RelayServer(
  port: 3000,
  enableAuth: true,
  apiKeyStoragePath: 'keys.json',
);
await authServer.start();

// Start a CLI agent
final agent = CliAgent(
  serverUrl: 'wss://your-server.com/ws/my-channel',
  targetUrl: 'http://localhost:8000',
  apiKey: 'dhk_xxx...', // optional
);
await agent.start();

🏗️ Architecture #

dhook/
├── bin/
│   └── dhook.dart              # CLI entry point
├── lib/
│   ├── dhook.dart              # Library exports
│   └── src/
│       ├── client/
│       │   └── cli_agent.dart        # WebSocket client
│       ├── server/
│       │   ├── relay_server.dart     # HTTP/WebSocket server
│       │   ├── api_key_manager.dart  # API key authentication
│       │   └── rate_limiter.dart     # DoS protection
│       ├── models/
│       │   └── webhook_payload.dart
│       └── utils/
│           └── logger.dart
├── Dockerfile
└── docker-compose.yml

🔒 Security Features #

• API Key Authentication: Secure channels with dhk_ prefixed tokens
• Rate Limiting: 100 requests/minute per IP (DoS protection)
• Body Size Limit: 1MB max for webhook payloads
• Cryptographic IDs: Secure channel ID generation
• TLS/SSL Support: Use with Nginx reverse proxy

📄 License #

MIT License - see LICENSE for details.

👤 Author #

Alisher Axmedov

• GitHub: @alisheraxmedov
• Email: alisheraxmedov4x4@gmail.com

🤝 Contributing #

We welcome contributions from the community! If you would like to contribute to this project, please read our Contributing Guidelines for detailed instructions on how to get started.