# Hookwave — full LLM-readable docs

> Security-first webhook gateway for AI / automation builders. Hookwave
> receives, verifies, transforms, and reliably delivers webhooks; lets
> developers replay past events without re-triggering the upstream
> provider; surfaces failures via an auto-grouping issues system; and
> exposes everything to AI agents through an MCP server.

This document concatenates Hookwave's product concepts, CLI reference,
and MCP / agent surface into a single file so an LLM can pull it into a
context window in one fetch.

---

## What Hookwave does

Hookwave sits between webhook senders and your code:

1. **Senders** (Stripe, GitHub, Shopify, Replicate, Twilio inbound,
   your own server, or a Hookwave-owned recurring schedule) POST events
   to a Hookwave ingest URL.
2. **Verification** — each source has a configured HMAC verifier
   (provider-specific signing scheme). Unsigned or tampered requests
   are dropped at the door.
3. **Connections** define which destinations receive a copy of each
   event, with optional JSONPath filters, body transformations, retry
   policy, outbound auth, and headers.
4. **Delivery** — Hookwave fans out the event to each matching
   destination (HTTP endpoint, Slack / Discord / Teams incoming
   webhook, Twilio SMS or WhatsApp, n8n / Make, Postgres / S3,
   Klaviyo, or a local CLI tunnel) with exponential backoff retries
   honoring per-status retry rules.
5. **Issues** auto-group failures (consecutive_failures,
   failure_rate, source_silent, schema_drift, status_code_seen,
   verification_failures) into a single open ticket with status and
   resolution flow.
6. **Replay** — every event keeps its captured body. `hookwave events
   replay <id>` re-delivers without re-triggering the upstream
   provider. Pass `--edit` to open the body in `$EDITOR` first.
7. **AI / MCP surface** — Hookwave ships an MCP server (over stdio)
   so Claude Desktop, Cursor, Continue, Claude Code, or any
   MCP-compatible client can list events, replay failures, and
   diagnose problems from inside an editor.

---

## Concepts

- **Source** — an inbound webhook channel. Has an ingest URL of the
  form `https://ingest.hookwave.dev/<source-id>` and a verifier
  (provider-specific HMAC scheme: Stripe `Stripe-Signature`, GitHub
  `X-Hub-Signature-256`, Shopify `X-Shopify-Hmac-SHA256`, Replicate
  webhook ID, or generic HMAC with a shared secret).
- **Destination** — an outbound delivery target. Settings that depend
  on the destination protocol (URL, auth, S3 bucket, Twilio account
  SID, Postgres DSN, Klaviyo API key) live on the destination row.
- **Connection** — source → destination wiring. Connection-level
  settings include: enabled/paused, filters (JSONPath expressions or
  event-type allowlists), template (handlebars-style body
  transformation), retry policy (max attempts + per-status overrides),
  outbound auth (bearer / api-key / basic), and additional headers.
  One source can fan out to many connections.
- **Event** — a single inbound request that's been captured. Stored
  with full body, headers, status, ingestion timestamp, and a stable
  `eventId` derived from the body when the sender doesn't provide one.
  Each event produces zero or more **deliveries** (one per matching
  connection).
- **Delivery** — one attempt to deliver an event to a destination.
  Tracks attempt count, last response code, last response body, and
  next-attempt timestamp.
- **Issue** — an auto-grouped delivery problem. Severity (low /
  medium / high), status (open / triaging / resolved), dedup window,
  auto-resolve interval, and notifications (in-app, email, Linear).
- **Trigger** — a rule that opens an issue when a condition is met
  for a connection / source. Built-in trigger types:
  `consecutive_failures`, `failure_rate`, `source_silent`,
  `verification_failures`, `status_code_seen`, `schema_drift`.

---

## CLI reference

Install with one of:

```sh
brew install hookwave/tap/hookwave    # macOS
curl -fsSL https://hookwave.dev/install.sh | sh   # Linux
npm install -g @hookwave/cli           # cross-platform
```

### Authentication

- `hookwave login` — opens a browser to authorise the CLI against the
  active org and stores a token in `~/.hookwave/auth.json`.
- `hookwave logout` — wipes the cached token.
- `hookwave whoami` — print the active org, email, and plan.

### Routing primitives

- `hookwave sources list` / `create` / `get <id>` / `update <id>` /
  `delete <id>`
- `hookwave destinations list` / `create` / `get <id>` / `update <id>` /
  `delete <id>`
- `hookwave connections list` / `create` / `get <id>` / `update <id>` /
  `delete <id>`

### Events

- `hookwave events list [--connection <id>] [--status <status>] [--since 1h]`
- `hookwave events get <id>` — show event body, headers, deliveries.
- `hookwave events replay <id> [--edit] [--connection <id>]` —
  re-deliver. `--edit` opens the body in `$EDITOR` so you can tweak
  a payload before re-firing.
- `hookwave events tail [--connection <id>]` — stream events in real
  time over WebSocket.

### Local development

- `hookwave listen <port>` — open a tunnel from the Hookwave cloud to
  your laptop. Live events fan out to `http://localhost:<port>`. Past
  events can be replayed through the tunnel with `--from`. Each tunnel
  also gets a stable HTTPS URL you can paste into a sender's webhook
  config so you don't need ngrok.
- `hookwave init` — interactive project bootstrapper. Picks a
  source provider, scaffolds a destination, and prints a one-liner
  for testing.
- `hookwave doctor <event-id>` — pattern-matched failure diagnosis.
  Returns ranked likely causes (signing mismatch, timeout, payload
  size, DNS / TLS, rate limits, persistent 5xx) with concrete
  remediation steps.

### Tokens

- `hookwave tokens list` / `create <name>` / `revoke <id>` — manage
  scoped API tokens for CI / non-interactive use.

### MCP / agent integration

- `hookwave mcp` — start the Hookwave MCP server over stdio. Pipe
  stdin/stdout into Claude Desktop, Cursor, Continue, Claude Code, or
  any MCP-compatible host. See the tool catalogue below.

---

## MCP tool catalogue

Tools exposed by `hookwave mcp` (and the dashboard's built-in
assistant):

- `hookwave_whoami` — identify the calling org, plan, and quota.
- `hookwave_list_sources(limit?, cursor?)` — paginated list.
- `hookwave_list_destinations(limit?, cursor?)`
- `hookwave_list_connections(limit?, cursor?)`
- `hookwave_create_destination({ name, destinationType, destinationUrl, ... })`
- `hookwave_create_connection({ sourceId, destinationId, ... })`
- `hookwave_list_events({ status?, connectionId?, sourceId?, limit?, cursor? })`
- `hookwave_get_event(id)` — full event including deliveries.
- `hookwave_list_issues({ status?, severity?, connectionId?, limit? })`
- `hookwave_get_issue(id)` — full issue with comments, representative
  trace, and grouped event IDs.
- `hookwave_replay_event(id, { connectionId? })` — re-deliver.
- `hookwave_doctor(eventId)` — diagnosis with ranked likely causes.

Calls are authenticated against the same JWT / API token the calling
client used to start the MCP server. Tools that mutate (create,
replay) honour the same org RBAC the dashboard uses — a viewer-role
member can't replay.

### Client configs

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hookwave": {
      "command": "hookwave",
      "args": ["mcp"]
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`) and **Continue** use the same shape.

**Claude Code** — `claude mcp add hookwave -- hookwave mcp`.

---

## Public URLs

- Marketing — `https://hookwave.dev`
- Pricing — `https://hookwave.dev/plans`
- AI feature page — `https://hookwave.dev/ai`
- Status — `https://hookwave.dev/status`
- Security — `https://hookwave.dev/security`
- CLI docs — `https://hookwave.dev/docs/cli`
- MCP docs — `https://hookwave.dev/docs/mcp`
- Signup — `https://hookwave.dev/signup`
- Login — `https://hookwave.dev/login`
- Ingest URL pattern — `https://ingest.hookwave.dev/<source-id>`
- API base — `https://api.hookwave.dev`

---

## Plans

Free, Pro, Team. Differences land on: event quota per month,
assistant tokens per month, schedules, audit log retention, custom
subdomain, and SLA. Live comparison at `/plans`.

---

## Support

- Email: `support@hookwave.dev`
- Security disclosure: `security@hookwave.dev` (see `/security` for
  the full policy and hall of fame).
- Status: `/status` shows live system status; the same data is
  available as JSON at `/api/status`.