# OpenWebhook CLI

Public npm CLI and MCP server for receiving OpenWebhook webhooks in a local
app. Requires Node.js 20.9 or later.

## Installation

```bash
npm install --global openwebhook
```

This repository does not publish the package automatically. For development:

```bash
npm install
npm run build
npm test
```

## Authentication

```bash
openwebhook auth owh_live_…
```

The token is stored in
`$XDG_CONFIG_HOME/openwebhook/config.json` (default
`~/.config/openwebhook/config.json`). The directory uses mode `0700` and the
file uses `0600`. `OPENWEBHOOK_TOKEN` supplies the token without writing a
file, and `OPENWEBHOOK_CONFIG` overrides the path.

## Local forwarding

```bash
openwebhook listen my-endpoint --port 3001
```

The CLI opens the authenticated SSE stream and forwards each webhook only to
`127.0.0.1:3001`. It keeps method, path, query, and body. It keeps request
headers except hop-by-hop headers, `Host`, `Content-Length`, proxy headers, and
`Forwarded` / `X-Forwarded-*`; `Host` and `Content-Length` are recalculated.

The local destination never comes from the event or the API: the host is fixed
to `127.0.0.1` and the port comes only from `--port`. Absolute paths,
protocol-relative URLs, backslashes, and newlines are rejected.

## MCP server

```bash
openwebhook mcp
```

The server uses JSON-RPC over stdio with `@modelcontextprotocol/sdk`. It does
not write logs to stdout. It exposes:

- `list_endpoints`
- `create_endpoint` (`slug`)
- `delete_endpoint` (`endpoint_id`, from `list_endpoints`)
- `watch`
- `unwatch`
- `wait_for_webhook` (optional `timeout_ms`, max 300000)
- `list_recent_webhooks` (optional `limit`, max 100)

`watch` keeps an SSE stream and an in-memory FIFO buffer of up to 100 events
per endpoint. `unwatch` drops that buffer. The process does not persist
payloads.

Example MCP client config:

```json
{
  "mcpServers": {
    "openwebhook": {
      "command": "openwebhook",
      "args": ["mcp"],
      "env": {
        "OPENWEBHOOK_TOKEN": "owh_live_…"
      }
    }
  }
}
```

## Configurable API

`OPENWEBHOOK_API_URL` changes the origin. It must use HTTP(S) and cannot
include credentials. The default is `https://openwebhook.co`.

The CLI uses this contract:

- `GET /api/pro/endpoints`
- `POST /api/pro/endpoints` with `{"slug":"..."}`
- `DELETE /api/pro/endpoints/:endpointId`
- `GET /api/events/:slug` with `Accept: text/event-stream`

Every request includes `Authorization: Bearer <token>`. Endpoint responses may
be a bare object or wrapped as `endpoints` / `endpoint`.

## Setup

### Claude Desktop (Desktop Extension)

1. Build the bundle from this package: `npm run package:mcpb`.
2. In Claude Desktop open **Settings → Extensions → Install from file**.
3. Choose `dist/openwebhook.mcpb`.
4. Paste your OpenWebhook API token from [https://openwebhook.co/dashboard](https://openwebhook.co/dashboard).
5. Reload extensions if Claude does not list the OpenWebhook tools yet.

The extension starts the MCP server with `OPENWEBHOOK_TOKEN` from that field.
You do not need to run `openwebhook auth` inside Claude Desktop.

### CLI

Install the npm package, run `openwebhook auth <token>`, then `openwebhook mcp`
or point your MCP client at the `openwebhook` binary as shown above.

## Privacy Policy

OpenWebhook's privacy policy: [https://openwebhook.co/privacy](https://openwebhook.co/privacy).