hookcatch

# HookCatch - Webhook Testing & Tunneling for OpenClaw

HookCatch is a webhook testing and localhost tunneling tool that lets you:
- Create webhook bins to capture and inspect HTTP requests
- Tunnel your localhost to test webhooks locally
- Manage bins and view captured requests programmatically

Perfect for testing webhook integrations (Stripe, Twilio, GitHub, etc.) from your OpenClaw skills.

## Quick Start

1. **Authenticate with HookCatch:**
   ```bash
   hookcatch login
   # Or use API token (recommended for automation):
   hookcatch token generate
   export HOOKCATCH_API_KEY="hc_live_..."
   ```

2. **Create a webhook bin:**
   ```bash
   hookcatch bin create --name "Test Stripe Webhooks"
   # Returns: https://hookcatch.dev/b/abc123xyz
   ```


3. **View created bins:**
   ```bash
   hookcatch bin list
   ```


4. **View captured requests:**
   ```bash
   hookcatch bin requests abc123xyz --format json
   ```
   OR

   ```bash
   hookcatch bin requests --binId abc123xyz --format json
   ```


## Available Commands

### Bin Management

**Create a new webhook bin:**
```bash
hookcatch bin create [--name "My Bin"] [--private] [--password "secret"] [--format json]
```
Options:
- `--name`: Optional bin name for organization
- `--private`: Create private bin (PLUS+ tier required)
- `--password`: Set password for private bin (min 4 chars)
- `--format`: Output format (`json` recommended for automation)

Returns: Bin ID, webhook URL, and view URL

**List your bins:**
```bash
hookcatch bin list [--format json]
```
Shows all your bins with request counts and status.

**Get requests for a bin:**
```bash
hookcatch bin requests <binId> [--limit 50] [--format json|table] [--method GET] [--password "secret"]
```
Options:
- `--limit`: Number of requests to fetch (default: 50)
- `--format`: Output format - `json` for scripts, `table` for viewing
- `--method`: Filter by HTTP method (GET, POST, etc.)
- `--pass...

# HookCatch Skill for OpenClaw

This OpenClaw skill enables your AI assistant to test webhooks and expose local services using [HookCatch](https://hookcatch.dev).

## Installation

### Via ClawHub (Recommended)

```bash
clawhub install hookcatch
```

### Manual Installation

1. Install the HookCatch CLI globally:
   ```bash
   npm install -g hookcatch
   ```

2. Install the OpenClaw skill wrapper (optional, provides better AI formatting):
   ```bash
   npm install -g @hookcatch/openclaw-skill
   ```

3. Copy this skill directory to your OpenClaw workspace:
   ```bash
   cp -r skills/hookcatch ~/.openclaw/skills/
   ```

4. Set up authentication:
   ```bash
   hookcatch login
   # Or generate an API token:
   hookcatch token generate
   export HOOKCATCH_API_KEY="hc_live_..."
   ```

5. Add the API key to your OpenClaw config (`~/.openclaw/openclaw.json`):
   ```json
   {
     "skills": {
       "entries": {
         "hookcatch": {
           "enabled": true,
           "apiKey": "hc_live_..."
         }
       }
     }
   }
   ```

## Usage

The skill provides two ways to interact with HookCatch:

1. **Direct CLI** (use `hookcatch` command directly)
2. **Skill Wrapper** (use `hookcatch-skill` for AI-optimized output)

The wrapper automatically:
- Formats output as JSON for better AI parsing
- Maps `HOOKCATCH_API_KEY` → `HOOKCATCH_TOKEN`
- Provides structured error messages
- Validates authentication before commands

## What is HookCatch?

HookCatch is a webhook testing and localhost tunneling tool that lets you:
- **Create webhook bins** to capture and inspect HTTP requests
- **Tunnel localhost** to test webhooks locally without deploying
- **Manage bins programmatically** via CLI

Perfect for testing integrations with Stripe, Twilio, GitHub, SendGrid, and any other webhook-based services.

## Usage Examples

### Create a Webhook Bin

Ask OpenClaw:
> "Create a HookCatch bin for testing Stri...