# OpenWebhook CLI

Receive webhooks on `127.0.0.1` without a tunnel. The first run does not need
an account. Requires Node.js 20.9 or later.

```bash
npm install --global openwebhook
openwebhook listen --port 3001
```

The CLI prints a temporary URL on `hooks.openwebhook.co` and forwards each
request to `127.0.0.1:3001`. The public URL returns that local status and body
while `listen` is connected. That URL expires after 24 hours. The anonymous
device token in `~/.openwebhook/config.json` (directory `0700`, file `0600`)
does not.

`OPENWEBHOOK_CONFIG` overrides the path. An existing
`~/.config/openwebhook/config.json` with an `owh_live_` token is still read.

## Permanent slugs

A Pro token keeps a stable URL such as `https://hooks.openwebhook.co/billing`.

```bash
openwebhook auth owh_live_…
openwebhook listen billing --port 3001
```

Generate the token once in the [developer dashboard](https://openwebhook.co/dashboard).
`OPENWEBHOOK_TOKEN` can supply it without writing it to disk. `auth` writes the
argument to the config file and links the device with that token, even if
`OPENWEBHOOK_TOKEN` is set. `listen` and `mcp` still prefer the environment
variable when it is present.

The local host is always `127.0.0.1`. The port comes only from `--port`.
Absolute paths, protocol-relative URLs, backslashes, and newlines are rejected.

## MCP

```bash
openwebhook mcp
```

No token is required for `url.inspect` or for watching the anonymous URL.
Permanent slugs need Pro. The process speaks JSON-RPC on stdio and does not
write logs to stdout.

| Tool | Without an account | With Pro |
| --- | --- | --- |
| `url.inspect` | Temporary ingest URL | Same |
| `watch.start` / `watch.stop` / `watch.wait` / `watch.list` | Anonymous URL | Also a named slug |
| `endpoint.list` / `endpoint.create` / `endpoint.delete` | Asks for an account | Named slugs |

`watch` keeps an in-memory buffer of up to 100 events. Nothing is written to
disk.

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

Add `OPENWEBHOOK_TOKEN` only when you want named slugs.

The server is listed as `co.openwebhook/mcp` in the
[MCP Registry](https://registry.modelcontextprotocol.io) and as a local
stdio bundle on [Smithery](https://smithery.ai/servers/openwebhook/openwebhook).
Install it with npm or `npx -y openwebhook mcp`.

## Claude Desktop

Install the Desktop Extension (`.mcpb`) from a release, or build it from this
repository with `npm run package:mcpb`. Leave the token field empty for an
anonymous URL. Paste a Pro token only for permanent slugs.

## Environment

| Variable | Purpose |
| --- | --- |
| `OPENWEBHOOK_API_URL` | API origin (`https://openwebhook.co`). HTTP(S) only, no credentials. |
| `OPENWEBHOOK_TOKEN` | Pro token instead of the config file |
| `OPENWEBHOOK_DEVICE_TOKEN` | Device token instead of the config file |
| `OPENWEBHOOK_CONFIG` | Alternate config path |

## Privacy

https://openwebhook.co/privacy