---

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.dev
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

Endpoint	Method	Description
/	GET	Health check
/new	GET	Generate new channel (redirects to /channel/
/ws/<channel>	WS	WebSocket connection for CLI
/webhook/<channel>	ANY	Receive webhooks
/webhook/<channel>/<path>	ANY	Receive webhooks with subpath
/api/keys	POST	Create new API key (auth mode)
/api/keys	GET	List registered channels (auth mode)

📦 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.

---