\r \r

HookCatch - Webhook Testing & Tunneling for OpenClaw\r

\r HookCatch is a webhook testing and localhost tunneling tool that lets you:\r

• Create webhook bins to capture and inspect HTTP requests\r
• Tunnel your localhost to test webhooks locally\r
• Manage bins and view captured requests programmatically\r \r Perfect for testing webhook integrations (Stripe, Twilio, GitHub, etc.) from your OpenClaw skills.\r \r

Quick Start\r

\r

1. Authenticate with HookCatch:\r

   hookcatch login\r
   # Or use API token (recommended for automation):\r
   hookcatch token generate\r
   export HOOKCATCH_API_KEY="hc_live_..."\r
   ```\r
   

\r 2. Create a webhook bin:\r

hookcatch bin create --name "Test Stripe Webhooks"\r
# Returns: https://hookcatch.dev/b/abc123xyz\r
```\r
\r
\r
3. **View created bins:**\r
```bash\r
hookcatch bin list\r
```\r
\r
\r
4. **View captured requests:**\r
```bash\r
hookcatch bin requests abc123xyz --format json\r
```\r
OR\r
\r
```bash\r
hookcatch bin requests --binId abc123xyz --format json\r
```\r
\r
\r
## Available Commands\r
\r
### Bin Management\r
\r
**Create a new webhook bin:**\r
```bash\r
hookcatch bin create [--name "My Bin"] [--private] [--password "secret"] [--format json]\r
```\r
Options:\r
- `--name`: Optional bin name for organization\r
- `--private`: Create private bin (PLUS+ tier required)\r
- `--password`: Set password for private bin (min 4 chars)\r
- `--format`: Output format (`json` recommended for automation)\r
\r
Returns: Bin ID, webhook URL, and view URL\r
\r
**List your bins:**\r
```bash\r
hookcatch bin list [--format json]\r
```\r
Shows all your bins with request counts and status.\r
\r
**Get requests for a bin:**\r
```bash\r
hookcatch bin requests \x3CbinId> [--limit 50] [--format json|table] [--method GET] [--password "secret"]\r
```\r
Options:\r
- `--limit`: Number of requests to fetch (default: 50)\r
- `--format`: Output format - `json` for scripts, `table` for viewing\r
- `--method`: Filter by HTTP method (GET, POST, etc.)\r
- `--password`: Password for private bins (if required; owners can use their auth token)\r
\r
**Show a single request:**\r
```bash\r
hookcatch request \x3CrequestId> \x3CbinId> [--format json|pretty] [--password "secret"]\r
```\r
\r
**Delete a bin:**\r
```bash\r
hookcatch bin delete \x3CbinId> --yes\r
```\r
\r
**Update a bin:**\r
```bash\r
hookcatch bin update \x3CbinId> --name "New Name"\r
hookcatch bin update \x3CbinId> --private --password "secret123"\r
hookcatch bin update \x3CbinId> --public\r
```\r
\r
**Show a single request:**\r
```bash\r
hookcatch request \x3CrequestId> \x3CbinId> [--format json|pretty]\r
```\r
\r
**Replay a request to a new URL:**\r
```bash\r
hookcatch replay \x3CbinId> \x3CrequestId> \x3Curl>\r
hookcatch replay --binId \x3CbinId> --requestId \x3CrequestId> --url \x3Curl>\r
```\r
\r
### Localhost Tunneling\r
\r
**Expose your localhost:**\r
```bash\r
hookcatch tunnel 3000\r
# Creates: https://hookcatch.dev/tunnel/xyz789\r
```\r
\r
**List active tunnels:**\r
```bash\r
hookcatch tunnel list\r
```\r
\r
**Stop a tunnel:**\r
```bash\r
hookcatch stop \x3CtunnelId>\r
```\r
\r
Forward incoming requests from the public URL to your local port 3000.\r
\r
**Tunnel limits:**\r
- FREE: 5 min/session, 3 sessions/day\r
- PLUS: 1h/session, unlimited\r
- PRO/ENTERPRISE: Unlimited\r
\r
### API Token Management\r
\r
**Generate long-lived API token:**\r
```bash\r
hookcatch token generate\r
# Store the token for automation\r
export HOOKCATCH_API_KEY="hc_live_..."\r
```\r
\r
**Check token status:**\r
```bash\r
hookcatch token status\r
```\r
\r
**Revoke token:**\r
```bash\r
hookcatch token revoke --yes\r
```\r
\r
**Account status:**\r
```bash\r
hookcatch status\r
hookcatch whoami\r
```\r
\r
## Usage Examples for OpenClaw Skills\r
\r
### Example 1: Test Stripe Webhooks\r
\r
```bash\r
# Create a bin for Stripe\r
BIN_URL=$(hookcatch bin create --name "Stripe Test" --format json | jq -r '.url')\r
\r
# Use this URL in Stripe dashboard as webhook endpoint\r
echo "Configure Stripe webhooks to: $BIN_URL"\r
\r
# Wait for webhooks...\r
sleep 10\r
\r
# Fetch and analyze captured webhooks\r
hookcatch bin requests abc123xyz --format json | jq '.[] | {event: .body.type, amount: .body.data.object.amount}'\r
```\r
\r
### Example 2: Test Local API\r
\r
```bash\r
# Start your local API on port 8000\r
# python -m http.server 8000 &\r
\r
# Expose it via tunnel\r
hookcatch tunnel 8000 --password \x3Cpassword>\r
\r
# Now external services can reach your local API via:\r
# https://hookcatch.dev/tunnel/xyz789\r
```\r
\r
### Example 3: Debug GitHub Webhooks\r
\r
```bash\r
# Create bin\r
hookcatch bin create --name "GitHub Webhooks"\r
\r
# In GitHub repo settings, add webhook URL\r
# Trigger events (push, PR, etc.)\r
\r
# View requests\r
hookcatch bin requests abc123xyz --method POST --limit 10\r
```\r
\r
## Integration with OpenClaw Skills\r
\r
When building OpenClaw skills that need to test webhooks:\r
\r
```javascript\r
// In your skill script\r
import { exec } from 'child_process';\r
import { promisify } from 'util';\r
\r
const execAsync = promisify(exec);\r
\r
// Create a bin\r
const { stdout } = await execAsync('hookcatch bin create --format json');\r
const { binId, url } = JSON.parse(stdout);\r
\r
// Use the webhook URL in your integration\r
console.log(`Webhook URL: ${url}`);\r
\r
// Later, fetch requests\r
const { stdout: requests } = await execAsync(\r
`hookcatch bin requests ${binId} --format json`\r
);\r
const captured = JSON.parse(requests);\r
\r
// Process captured webhooks\r
for (const req of captured) {\r
console.log(`${req.method} ${req.path}: ${JSON.stringify(req.body)}`);\r
}\r
```\r
\r
## Environment Variables\r
\r
- `HOOKCATCH_API_KEY` - API token for authentication (recommended for automation)\r
- `HOOKCATCH_API_URL` - Override API URL (default: https://api.hookcatch.dev)\r
\r
\r
## Benefits for OpenClaw Users\r
\r
- **No more ngrok setup**: Use HookCatch tunnels for quick local testing\r
- **Webhook inspection**: See exactly what Stripe/Twilio/etc. is sending\r
- **Automation-friendly**: JSON output for easy parsing in skills\r
- **Private bins**: Keep your test data secure with password protection\r
- **Fast & simple**: One command to create bins or tunnels\r
\r
## Getting Help\r
\r
- Documentation: https://docs.hookcatch.dev\r
- Discord: Join #hookcatch in OpenClaw Discord\r
- GitHub: https://github.com/hookcatch/cli\r
- Email: [email protected]\r
\r
## Tips\r
\r
1. **Use API tokens for skills**: Generate a token once and use it in `HOOKCATCH_API_KEY`\r
2. **JSON format for automation**: Always use `--format json` when parsing in scripts\r
3. **Private bins for sensitive data**: Use `--private` for production webhook testing\r
4. **Clean up after testing**: Delete bins with `hookcatch bin delete` to stay within limits\r
\r
---\r
\r
**Built for OpenClaw by the HookCatch team** 🪝\r