Install and log in
Install the Hookspot CLI and log in to start receiving webhooks.
The Hookspot CLI, hookspot, brings webhooks to your terminal and forwards them
to the app on your machine. Install it and log in to start testing.
Install the CLI
Section titled “Install the CLI”In any directory, install the CLI with npm (Node.js 18 or newer):
npm install -g @hookspot/cliOn macOS or Linux, you can use Homebrew instead:
brew install hookspot/hookspot/hookspot-cliWithout Node.js or Homebrew, download the archive for your system from the
latest release. Its
INSTALL.md lists the steps.
Log in
Section titled “Log in”hookspot login opens your browser and prints a code:
hookspot login╭─ Log in ──────────────────────────╮│ Confirm this code in your browser ││ ││ 2NCL-AXSJ │╰───────────────────────────────────╯https://<hookspot-host>/cli/login/<token>○ Waiting for approval… (Ctrl+C to cancel)✓ Logged in as [email protected]✓ Active project set to Documentation demo | Default projectIn the browser:
- Sign in to Hookspot if it asks.
- Check that the Confirmation code matches the code in your terminal.
- Pick an Organization and a Project.
- Click Approve login.
The CLI saves a CLI key and the project you picked, then prints the last two lines. If no browser opens, for example on a remote machine, open the printed URL on your own computer. The link expires after 10 minutes.
Check the project
Section titled “Check the project”hookspot listen uses one project, the CLI’s active project. List the projects
you can open:
hookspot project list╭─ Projects ──────────────────────────────────────────────────────────────── 1 ─╮│ UID ORGANIZATION PROJECT │├───────────────────────────────────────────────────────────────────────────────┤│ proj_TgGWpwkrXkmA06kUc8LY1PaoCq Documentation demo Default project active │╰───────────────────────────────────────────────────────────────────────────────╯active marks the CLI’s active project. To switch, see
Choose the CLI’s project.
Use a CLI key in CI
Section titled “Use a CLI key in CI”For a CI job, set HOOKSPOT_CLI_KEY to authenticate without a browser login.
- In Hookspot, open the user menu and click Account settings.
- Select CLI key and copy the key.
- In your CI system, save the key as a secret and expose it as the
environment variable
HOOKSPOT_CLI_KEY.
In the job, pass the project’s UID from hookspot project list:
hookspot --project proj_TgGWpwkrXkmA06kUc8LY1PaoCq listen --forward-to http://localhost:3000╭─ Listening in Documentation demo | Default project ───────────────────────── 1 source • 1 route ─╮│ Docs demo https://<webhook-host>/RtXNHZuNw0VPjir0kS0v9L2sgE ││ → http://localhost:3000/webhooks │╰──────────────────────────────────────────────────────────────────────────────────── ctrl-c quit ─╯Connecting…Ready. Waiting for requests (Ctrl-C to quit)No requests yet. Check the whole path with a test event:
curl -X POST 'https://<webhook-host>/RtXNHZuNw0VPjir0kS0v9L2sgE' -H 'Content-Type: application/json' -d '{"type":"hookspot.test"}'#1 POST Docs demo /webhooks order.created 200 3ms 22:42:24.746This is the CLI’s plain-text output. Wait
for the Ready. line before the job sends webhooks.
Upgrading
Section titled “Upgrading”Upgrade the CLI the way you installed it. For npm, run:
npm install -g @hookspot/cli@latestFor Homebrew, run:
brew upgrade hookspot-cliFor Docker, pull the newest image:
docker pull hookspot/cliFor a release archive, take these steps:
- Download the new archive for your system from the latest release.
- Replace the executable you installed with the one inside, as the archive’s
INSTALL.mddescribes.
hookspot listen in a terminal and
hookspot version tell you when a
newer release is out. Check the upgrade with hookspot version, or with
docker run --rm hookspot/cli version for Docker.
A CLI version stops working only when Hookspot drops something that version
needs. hookspot listen warns you at least 30 days before that version stops
working, unless a security fix cannot wait.