openwebhook

OpenWebhook CLI

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

Installation

npm install --global openwebhook

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

npm install
npm run build
npm test

Authentication

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

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

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:

{
  "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)

• Build the bundle from this package: npm run package:mcpb.
• In Claude Desktop open Settings → Extensions → Install from file.
• Choose dist/openwebhook.mcpb.
• Paste your OpenWebhook API token from https://openwebhook.co/dashboard.
• 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.