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.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. Create API Key

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...", ...}

3. CLI Agent (on your machine)

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

4. 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 (auth enabled by default)
dhook server

# Start on custom port
dhook server --port 8080

# Disable auth (local development only)
dhook server --port 3000 --no-auth

Client Commands

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 relay server (auth enabled by default)
final server = RelayServer(
  port: 3000,
  apiKeyStoragePath: 'keys.json',
);
await server.start();

// Start a CLI agent with API key
final agent = CliAgent(
  serverUrl: 'wss://your-server.com/ws/my-channel',
  targetUrl: 'http://localhost:8000',
  apiKey: 'dhk_xxx...',
);
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.

☕ Support

If you find DHOOK useful, consider buying me a coffee!

---

Made with ❤️ in Uzbekistan 🇺🇿