Listen and forward
Watch webhooks arrive in your terminal and forward them to your app.
hookspot listen shows your project’s webhooks in your terminal and forwards
them to your app when you set --forward-to. Use it to inspect requests,
send test events and replay a webhook after changing your code.
Forward to your app
Section titled “Forward to your app”After logging in, run this in any directory with your app listening on port 3000:
hookspot listen --forward-to http://localhost:3000The CLI opens a full-screen view. The list holds each request, and the panel below it shows the selected one.

The key bar at the bottom names the main keys. Press ? for all of them.
The CLI adds the route’s path to the address in --forward-to. Keep that
address at your app’s root:
--forward-to |
Route path | Your app gets |
|---|---|---|
http://localhost:3000 |
/webhooks |
http://localhost:3000/webhooks |
http://localhost:3000/dev |
/webhooks |
http://localhost:3000/dev/webhooks |
--forward-to 3000 is short for http://localhost:3000. Your app gets the
webhook’s method, query, body and most of its headers. It has 30 seconds to
answer, and the CLI does not follow redirects.
Without a source name, the CLI listens to every source that has a route. To
listen to some sources only, name them exactly, such as
hookspot listen "Docs demo". Deliveries of the other sources are then
Skipped, unless another CLI listens to them.
Without --forward-to, the CLI only shows each webhook. It is still a
listener, and answers each of its deliveries with an empty 200.
Keep your app’s response body under 3 MiB. Deliveries says what Hookspot records of a larger one.
Use the full-screen view
Section titled “Use the full-screen view”| Key | Action |
|---|---|
↑ ↓ |
Select a request. The list stops following the newest one. |
f |
Follow the newest request again. |
← → |
Switch the tabs: Overview, Request, Response and Timing. |
pgup pgdn |
Scroll the selected request. |
/ |
Filter the list. ↵ applies the filter, and esc clears it. |
r |
Replay the selected request to your app. |
w |
Wait for your app to start, then replay. |
t |
Send a test event. |
c |
Copy the request as a curl command. |
e |
Export the request to hookspot-fixtures/ in the current directory. |
s |
Open the Sources page: each source’s webhook URL, routes and counts. |
? |
Show every key. |
q |
Stop listening. |
A filter shows the requests that match all of its terms. Type status:error,
status:4xx or status:422 for statuses, and source: or path: with the
start of a name or path. Any other word matches the path and the event type.
c copies through your terminal, which must allow clipboard access.
Terminal.app does not, so use the stream’s c N there. It also prints the
command.
The printed command hides sensitive header values unless you pass
--show-sensitive-headers.
Send a test event
Section titled “Send a test event”Press t. The CLI posts a hookspot.test event to the source’s webhook URL,
and the request takes the same path as any webhook. The CLI marks its delivery
test and prints ✓ path works with how far the request got.
The test request shows under Requests in the app, and its deliveries count toward the monthly limit.
The test carries no signature or credentials. If the source
verifies its senders, Hookspot rejects it, and
the CLI reports 401 Unauthorized.
Replay a request
Section titled “Replay a request”After changing your code, select a request and press r to test the same
webhook again. The CLI adds the result to its list. The stream shows what
changed in your app’s response:
#2 ↻ #1 422 → 200 3ms → 1ms Docs demo · POST /webhooks 22:54:50.718 - "error": "missing customer_id" + "received": trueA replay stays in the CLI. Hookspot records no attempt, and the delivery keeps its outcome. To record a new attempt, retry the delivery.
Print a stream
Section titled “Print a stream”--stream prints each request as it arrives, with a › prompt at the bottom:
hookspot listen --stream --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 │╰──────────────────────────────────────────────────────────────────────────╯No requests yet. Check the whole path with a test event:
t send a test event to Docs demo
or from anywhere: curl -X POST 'https://<webhook-host>/RtXNHZuNw0VPjir0kS0v9L2sgE' -H 'Content-Type: application/json' -d '{"type":"hookspot.test"}'╭─ #1 Docs demo · POST /webhooks ────────────────── test 22:54:46.831 ─╮│ 422 Unprocessable Entity 3ms → http://localhost:3000/webhooks ││ req_Rphx5soGtOEVflVEp9va46cCO4 │├─ request · application/json · 64 B ─────────────────────────────────────┤│ { ││ "type": "hookspot.test", ││ "sent_at": "2026-10-02T19:54:46.698976Z" ││ } │├─ response · application/json · 31 B ────────────────────────────────────┤│ { ││ "error": "missing customer_id" ││ } │╰─────────────────────────────────────────────────────────────────────────╯✓ path works: hookspot → this terminal → http://localhost:3000/webhooks#2 ↻ #1 422 → 200 3ms → 1ms Docs demo · POST /webhooks 22:54:50.718 - "error": "missing customer_id" + "received": true● live · Documentation demo | Default project · 1 request · 0 ok · 1 failed…› ↵ replay last · r N replay #N · t test event · ? help · ctrl-c quitHere t sent a test event, the app answered 422, and ↵ replayed it after
the fix. Type these commands at the prompt and press ↵:
| Command | Action |
|---|---|
↵ |
Replay the last request. |
r N |
Replay request #N. |
c N |
Copy request #N as a curl command, and print it. |
e N |
Export request #N to hookspot-fixtures/. |
t [SOURCE] |
Send a test event. |
? |
Show the commands. |
When its output goes to a pipe or a file, the CLI prints plain text instead, as in Use a CLI key in CI.
Run several listeners
Section titled “Run several listeners”Run a second hookspot listen beside the CLI from
Forward to your app, forwarding only Docs demo to
another app:
hookspot listen "Docs demo" --forward-to http://localhost:4000Each running hookspot listen is a listener. Each webhook to Docs demo now
reaches both apps. Deliveries lists one
delivery per route for each listener, with its
own answer, and each one counts.
Other members of the organization can run listeners on the project too.
Replay in the app makes a new request, and every listener of its source gets its own delivery of it. Retries explains where a retry goes.
Handle a burst
Section titled “Handle a burst”With hookspot listen --forward-to http://localhost:3000 running and a handler
that waits 10 seconds, send 60 webhooks to the webhook URL from the source’s
Overview:
curl '<webhook-url>?n=[1-60]' -H 'content-type: application/json' --data-raw '{"type":"order.created"}'{"status":"ok","request_id":"req_Lyg8AfGRrYwpKF2hnqSXMywquE"}{"status":"ok","request_id":"req_cc6qqFWbk5bxxAViZHhYA7rzEK"}…Each listener has a soft limit of 50 buffered deliveries. Open Deliveries. About 50 rows read Pending · Sent, and the newest read Pending · Queued until your app’s answers make room.
Each delivery counts toward your monthly usage.
To see a listener leave:
- Press
q, orCtrl-Cin any view, while rows read Pending · Queued. - Run the same
hookspot listencommand within 5 minutes.
Those rows keep going out. If you stay away longer, they become Skipped. Rows that read Pending · Sent become Failed, and you can retry them.
To see a pause:
- Send the burst again.
- Open Routes and click the check mark on the route’s line.
- Click Pause while rows on Deliveries read Pending · Queued.
- Wait until no row on Deliveries reads Pending · Queued. Those rows become Skipped as their turn comes, which can take a couple of minutes.
- On Routes, click the paused line.
- Click Resume.
- On Deliveries, click Retry N skipped.
Those rows go out as your listener has room.
Stop listening
Section titled “Stop listening”Press q in the full-screen view, or Ctrl-C in any view. Webhooks Hookspot
routes while no CLI listens are Skipped. Start the CLI again, then
retry them.
Deliveries already waiting for this listener become Skipped after at least 5
minutes. Start hookspot listen before then, and it takes them if it runs on the
same machine with the same --forward-to, listening to their source.
Listeners that leave explains the
rest.
Deliveries the CLI already has become Failed, and you can retry them.
If the network drops, the CLI reconnects on its own and keeps its waiting
deliveries if it is back within 5 minutes. Back online, it prints Reconnected with how long it was offline.
Retry the Skipped and Failed deliveries from that time in the app.