Skip to content
WebsitePlatform

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.

After logging in, run this in any directory with your app listening on port 3000:

hookspot listen --forward-to http://localhost:3000

The CLI opens a full-screen view. The list holds each request, and the panel below it shows the selected one.

The CLI's full-screen view lists request 1 from Docs demo to /webhooks with status 200. Its details show 200 OK from http://localhost:3000/webhooks.

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.

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.

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.

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": true

A replay stays in the CLI. Hookspot records no attempt, and the delivery keeps its outcome. To record a new attempt, retry the delivery.

--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 quit

Here 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 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:4000

Each 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.

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:

  1. Press q, or Ctrl-C in any view, while rows read Pending · Queued.
  2. Run the same hookspot listen command 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:

  1. Send the burst again.
  2. Open Routes and click the check mark on the route’s line.
  3. Click Pause while rows on Deliveries read Pending · Queued.
  4. Wait until no row on Deliveries reads Pending · Queued. Those rows become Skipped as their turn comes, which can take a couple of minutes.
  5. On Routes, click the paused line.
  6. Click Resume.
  7. On Deliveries, click Retry N skipped.

Those rows go out as your listener has room.

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.