How the CLI Works

Overview

The HookBridge CLI bridges the gap between external webhook providers and your local development server. Instead of exposing your machine to the internet, webhooks flow through HookBridge infrastructure and are streamed to your CLI in real time.

Flow

1. You configure a webhook provider (Stripe, GitHub, etc.) to send events to your HookBridge Webhook URL.
2. HookBridge receives the webhook at its public endpoint, validates it, and stores the payload durably.
3. The CLI receives the webhook over a persistent WebSocket connection within milliseconds.
4. The CLI forwards it locally as an HTTP POST to your development server (e.g., http://localhost:3000), preserving the original headers, body, and content type.
5. The local response (status code and latency) is displayed in your terminal.

Real-Time Delivery

The CLI maintains a WebSocket connection to the HookBridge streaming service. When a webhook arrives at your endpoint, it is published to the CLI in real time — typically within milliseconds of the original request.

This means your development workflow is fast: trigger an event in Stripe, and it hits your local server almost instantly.

Automatic Reconnection

If the WebSocket connection drops (network change, laptop sleep, etc.), the CLI automatically attempts to reconnect with exponential backoff. If reconnection fails after several attempts, it switches to a polling fallback that queries the HookBridge API for new messages.

While polling, the CLI periodically retries the WebSocket connection. When the connection is restored, it switches back to real-time streaming.

This means you do not lose webhooks during brief disconnections — they are stored by HookBridge and delivered when connectivity resumes.

Stable Webhook URLs

CLI-mode endpoints persist across sessions. The Webhook URL you configure in your provider settings stays the same whether the CLI is running or not. Webhooks that arrive while the CLI is offline are stored by HookBridge and available when you reconnect.

What Is a CLI-Mode Endpoint?

A CLI-mode inbound endpoint is a standard HookBridge inbound endpoint with mode set to cli. The key difference from a regular (forward) inbound endpoint:

• Forward mode: HookBridge receives the webhook and delivers it to a configured destination URL over the internet.
• CLI mode: HookBridge receives the webhook and streams it to connected CLI clients instead.

All other inbound features work the same in both modes — verification options (HMAC, static token, IP allowlist), idempotency, message storage, and replay are all available.

Security

• No inbound ports: Your machine does not need to be publicly accessible. The CLI connects outbound to HookBridge over HTTPS/WSS.
• API key authentication: The CLI authenticates with your API key. Only authenticated clients with access to the endpoint can receive webhooks.
• Credentials stored locally: Your API key is saved in a local config file with restricted permissions.
• TLS everywhere: All communication between the CLI and HookBridge uses TLS encryption.

Console Visibility

Webhooks received through the CLI appear in the HookBridge console alongside your other inbound messages. You can inspect payloads and replay messages — the same tools available for production inbound endpoints.