Project: hookd-client - The Ruby Toolbox

A lightweight, high-performance interaction server for capturing DNS and HTTP callbacks. Perfect for security testing, debugging webhooks, and monitoring external service integrations.

Overview

Hookd provides ephemeral endpoints that capture and store DNS queries and HTTP requests. Each registered hook gets unique DNS and HTTP(S) endpoints that can be used to detect out-of-band interactions.

Key Features

🚀 High Performance - Handles dozens of requests per second
💾 Memory Efficient - With configurable eviction
📊 Observable - Built-in metrics and structured logging
🎯 Simple - Single binary, YAML configuration, no dependencies

Architecture

Hookd consists of two main components:

Server

The core interaction server written in Go that captures DNS and HTTP callbacks.

📖 Server Documentation

Features:

DNS server (port 53)
HTTP/HTTPS server with wildcard vhost
RESTful API for hook management
Automatic Let's Encrypt TLS certificates
Multi-strategy eviction system
Real-time metrics endpoint

Clients

Client libraries for interacting with the Hookd server:

Ruby Client

Ruby client for seamless integration into Ruby applications and security testing tools.

📖 Ruby Client Documentation

require 'hookd'

client = Hookd::Client.new(
  server: "https://hookd.example.com",
  token: ENV['HOOKD_TOKEN']
)

hook = client.register
puts "DNS: #{hook.dns}"
puts "HTTP: #{hook.http}"

interactions = client.poll(hook.id)

Quick Start

1. Deploy the Server

Available binaries:

hookd-linux-amd64 - Linux x86_64
hookd-linux-arm64 - Linux ARM64
hookd-darwin-amd64 - macOS Intel
hookd-darwin-arm64 - macOS Apple Silicon

Download from latest build artifacts.

chmod +x hookd-linux-amd64
sudo mv hookd-linux-amd64 /usr/local/bin/hookd

# Create config directory
sudo mkdir -p /etc/hookd
sudo cp server/config.example.yaml /etc/hookd/config.yaml

# Create certs directory (for Let's Encrypt)
sudo mkdir -p /var/lib/hookd/certs

# Run
sudo hookd --config /etc/hookd/config.yaml

2. Install a Client

Ruby:

gem install hookd-client

cURL:

# Register hook
curl -X POST https://hookd.example.com/register \
  -H "X-API-Key: YOUR_TOKEN"

# Poll interactions
curl https://hookd.example.com/poll/HOOK_ID \
  -H "X-API-Key: YOUR_TOKEN"

API Reference

Core Endpoints

Endpoint	Method	Description
`/register`	POST	Create one or more hooks with DNS/HTTP endpoints
`/poll/:id`	GET	Retrieve and delete interactions for a single hook
`/poll`	POST	Batch poll multiple hooks in one request
`/metrics`	GET	Get server statistics (public)

Response Format

Register (single hook):

{
  "id": "abc123",
  "dns": "abc123.hookd.example.com",
  "http": "http://abc123.hookd.example.com",
  "https": "https://abc123.hookd.example.com",
  "created_at": "2025-10-01T10:30:00Z"
}

Register (multiple hooks):

curl -X POST https://hookd.example.com/register \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 5}'

{
  "hooks": [
    {
      "id": "abc123",
      "dns": "abc123.hookd.example.com",
      "http": "http://abc123.hookd.example.com",
      "https": "https://abc123.hookd.example.com",
      "created_at": "2025-10-01T10:30:00Z"
    },
    {
      "id": "def456",
      "dns": "def456.hookd.example.com",
      ...
    }
  ]
}

Poll (single hook):

{
  "interactions": [
    {
      "id": "int_xyz",
      "type": "dns",
      "timestamp": "2025-10-01T10:31:00Z",
      "source_ip": "1.2.3.4",
      "data": {
        "qname": "abc123.hookd.example.com",
        "qtype": "A"
      }
    },
    {
      "id": "int_abc",
      "type": "http",
      "timestamp": "2025-10-01T10:32:00Z",
      "source_ip": "5.6.7.8",
      "data": {
        "method": "POST",
        "path": "/callback",
        "headers": {...},
        "body": "payload"
      }
    }
  ]
}

Poll (batch - multiple hooks):

curl -X POST https://hookd.example.com/poll \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["abc123", "def456", "ghi789"]'

{
  "results": {
    "abc123": {
      "interactions": [
        {
          "id": "int_xyz",
          "type": "dns",
          "timestamp": "2025-10-01T10:31:00Z",
          "source_ip": "1.2.3.4",
          "data": {
            "qname": "abc123.hookd.example.com",
            "qtype": "A"
          }
        }
      ]
    },
    "def456": {
      "interactions": []
    },
    "ghi789": {
      "error": "Hook not found"
    }
  }
}

Documentation

Server Setup & Configuration - Complete server deployment guide
Ruby Client API - Ruby client documentation and examples

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE for details

hookd-client

Runtime