Hookbin

Edge-first Request Bin and Response Mocker built with Nuxt 4 and Cloudflare Workers

Live Demo: hookbin.pages.dev

Hookbin is a developer tool for debugging webhooks and testing API integrations. It captures HTTP requests in real-time and allows you to configure custom mock responses.

Features

• Request Inspection: Capture and view all request details (headers, body, query params)
• Real-time Updates: See requests appear instantly using Server-Sent Events
• Mock Responses: Return custom status codes, content types, and response bodies
• Secure Bin IDs: Cryptographically secure UUIDv4-based identifiers (128-bit randomness)
• No Authentication: Simple capability-based URLs - bin IDs act as secrets
• Auto-Expiring Logs: All request logs automatically expire after 24 hours
• Edge-First: Deployed on Cloudflare Workers for global low-latency access

Tech Stack

• Framework: Nuxt 4 (with compatibility version 4)
• Deployment: Cloudflare Workers / Cloudflare Pages
• Storage: Cloudflare Workers KV
• Styling: TailwindCSS
• Utils: VueUse, Shiki (syntax highlighting)

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended)
• Cloudflare account (for production deployment)

Installation

# Install dependencies
pnpm install

# Start development server
pnpm dev

The app will be available at http://localhost:3000

Local Development

Nuxt automatically uses Miniflare for local KV storage during development, so you don't need to set up Cloudflare KV locally.

Usage

Creating a Bin

1. Visit the home page
2. Click "Create New Bin"
3. You'll be redirected to your bin's page with a unique URL

Capturing Requests

Send HTTP requests to your bin URL:

curl -X POST https://your-domain.com/api/YOUR_BIN_ID \
  -H "Content-Type: application/json" \
  -d '{"hello": "world"}'

The request will appear in real-time on the bin page.

Configuring Mock Responses

1. Navigate to your bin page
2. Click "Configure Mock"
3. Set status code, content-type, and response body
4. Save the mock

Now all requests to your bin will return the mock response without being logged.

Deployment

Cloudflare Pages

1. Create KV Namespaces:

wrangler kv:namespace create "HOOKBIN_KV"
wrangler kv:namespace create "HOOKBIN_KV" --preview

2. Update wrangler.toml with the KV namespace IDs

3. Build and Deploy:

pnpm build
pnpm deploy

Alternatively, connect your GitHub repository to Cloudflare Pages for automatic deployments.

Project Structure

hookbin/
├── app/
│   ├── components/      # Vue components
│   ├── composables/     # Reusable logic
│   ├── layouts/         # Page layouts
│   └── pages/           # Routes
├── server/
│   ├── api/             # API endpoints
│   └── utils/           # Server utilities
├── shared/
│   └── types/           # TypeScript interfaces (shared between app & server)
├── public/              # Static assets
├── nuxt.config.ts       # Nuxt configuration
├── wrangler.toml        # Cloudflare Workers config
└── package.json

API Endpoints

Create Bin

POST /api/bins/create

Creates a new bin and returns its ID and URL.

Ingest (Main Endpoint)

ANY /api/{binId}

Accepts all HTTP methods. Checks for mock response first, otherwise logs the request.

Get Logs

GET /api/bins/{binId}/logs?limit=50

Retrieves captured request logs for a bin.

Real-time Stream (SSE)

GET /api/bins/{binId}/stream

Server-Sent Events endpoint for real-time log updates.

Mock Configuration

GET    /api/bins/{binId}/mock    # Get current mock
POST   /api/bins/{binId}/mock    # Set/update mock
DELETE /api/bins/{binId}/mock    # Remove mock

Security

Bin ID Generation

Bin IDs are generated using cryptographically secure UUIDv4:

• 128 bits of randomness (32 hexadecimal characters)
• Uses Web Crypto API (crypto.randomUUID() or crypto.getRandomValues())
• Probability of collision: ~1 in 5.3 × 10³⁶
• Bin IDs act as capability URLs - treat them as secrets

Security Best Practices:

• Don't share bin URLs publicly if capturing sensitive data
• Logs auto-expire after 24 hours
• No authentication required - possession of bin ID grants access

Configuration

Environment Variables

No environment variables required for basic operation. KV bindings are configured in nuxt.config.ts and wrangler.toml.

Tailwind CSS

Tailwind is configured with a custom blue primary color palette. Modify tailwind.config.ts to customize.

Development Guidelines

• All comments must be in English
• Use TypeScript strict mode
• Prefer Composition API for Vue components
• Use Nuxt auto-imports where possible
• Keep code Edge-compatible (no file system, no Node.js-specific APIs)

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please follow the coding standards outlined in CLAUDE.md.