SignalBin Docs

Appearance

CLI ​

SignalBin has an official command-line client. Its most useful job is forwarding an endpoint's captures straight to a server running on your own machine while you develop, without standing up a real destination.

The project is published as signalbin-cli; the binary it installs is called signalbin.

Install ​

sh
curl -fsSL https://raw.githubusercontent.com/starfront-ventures/signalbin-cli/main/install.sh | sh

That installs the latest release for Linux or macOS. If you'd rather build it yourself, go install github.com/starfront-ventures/signalbin-cli/cmd/signalbin@latest works, and Windows binaries are on the releases page.

Authenticate ​

The CLI can't create its own token. Make one in the web app first: Settings in the sidebar, the API Tokens tab, then New token. A token with webhooks:read covers everything on this page, so switching on Read for Webhooks is enough. Save it with:

sh
signalbin auth login --token sb_live_...
signalbin auth whoami

auth whoami reports the user, workspace, and the token's granted scopes, which is the quickest way to check a token does what you expect. Per invocation, --token (or $SIGNALBIN_TOKEN) and --server (or $SIGNALBIN_SERVER) override what's saved.

Forward captures to your local server ​

sh
signalbin listen <endpoint-id> --forward http://localhost:3000

Every webhook the endpoint captures gets delivered to your local server as it arrives, with the captured request's path and query string appended to the base URL you pass. Headers can be adjusted on the way out the way a destination's rules would: --strip Header-Name drops one, --add Name=Value sets one, and both are repeatable. Without --forward, listen only prints each capture as it lands: nothing is delivered anywhere and nothing is recorded.

Underneath, listen is an ordinary API client. It subscribes to the real-time event stream (GET /api/v1/events), fetches each capture, and delivers it locally itself. There's no privileged internal channel involved, so anything listen does you can do from your own tooling.

listen has two visible side effects:

  • While connected, the session appears on that endpoint's Destinations tab as a cli-kind entry, badged Live CLI session with a status of Connected. It's a visibility marker, not a relay target: SignalBin's servers never dial it, it doesn't count against the 10-destination cap, and it goes away when you disconnect.
  • Each local delivery gets reported back through a record-only endpoint (POST /api/v1/webhooks/{id}/replays), so it shows up in that capture's Deliveries section alongside server-driven replays, labelled Manual replay. That's a separate route from the one that triggers a delivery from SignalBin's side (POST /api/v1/webhooks/{id}/replay, see Webhooks & Replay).

TIP

This is how you receive webhooks on localhost. A real http destination can't reach your machine anyway, since loopback and link-local target URLs are rejected as a deliberate SSRF guard. See Endpoints & Destinations for that restriction.

Beyond listen ​

The rest of the REST API is wrapped too, grouped as auth, stats, endpoints, mock-rules, destinations, samples, webhooks, listen, billing, team, and update. Run signalbin <group> --help for the current command reference, and add --json to any command for machine-readable output.

Next steps ​