How to recover webhooks that arrived while your laptop was off

When your laptop is off, no Hookspot listener can forward a webhook to your app. Hookspot can store the request, but starting the listener later does not deliver it automatically. You must retry the skipped delivery.

This walkthrough creates that state on purpose. You will stop every listener for one source, send a controlled webhook, restart the listener, and click Retry delivery.

Prerequisites

Complete the Node.js setup tutorial first. You need its fixed receiver.js, order-created.json, /webhooks/orders route, and three terminals.

You also need access to the Hookspot app and the source’s complete private Webhook URL. Keep that URL out of screenshots, logs, and version control.

The experiment leaves the Node receiver running so you can see the recovered request arrive. Turning off a laptop would stop both processes, but the delivery state tested here comes from having no listener for the source.

Start the receiver

Keep the fixed receiver from the setup tutorial running. If you stopped it, run this in the receiver terminal from hookspot-node-example/:

node receiver.js

The receiver prints:

Listening on http://localhost:3000

Leave this process running. The fixed handler accepts the controlled order.created payload and logs each request it receives.

Stop every listener for the source

A running hookspot listen process creates a listener. One remaining listener changes this experiment, so stop every listener that covers the tutorial source.

In each full-screen Hookspot terminal, press q. In another CLI view, press Ctrl-C. If another organization member is listening to the same source, ask them to stop that listener for this test.

Keep the Node receiver running. Stopping the receiver while a listener remains active tests an app error instead of an offline listener.

Send one webhook with no listener

In the sender terminal, enter hookspot-node-example/. Set WEBHOOK_URL to the complete private URL, as in the setup tutorial. Send the payload:

curl --request POST \
  --header 'Content-Type: application/json' \
  --data-binary @order-created.json \
  "$WEBHOOK_URL"

The sender is the service that sends the webhook. Hookspot normally answers the sender with 200 after storing the request. That response does not mean your app received it.

The receiver prints no new order line because no listener was available to forward this request.

Inspect the skipped delivery

Open Requests in the Hookspot app and select the new request. Confirm that Hookspot stored the controlled order.created body and shows a Skipped outcome.

Open Deliveries. The matching row has an Attempts count of 0. Select it and confirm:

• its status is Skipped
• Listener is None
• Attempts is None yet
• the Fix it panel asks you to start the CLI and retry

Zero attempts matters. Hookspot had no listener to send this delivery through, so your handler did not return an error.

Restart the listener

In the Hookspot terminal, enter hookspot-node-example/ and run:

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

Wait until the delivery’s Fix it panel shows Your CLI is connected.

The receiver still prints no new order line. Reconnecting makes the listener available for new deliveries, but it does not catch up the skipped delivery.

Retry the delivery manually

With the skipped delivery still selected, click Retry delivery in the Hookspot app. This is the manual recovery step. Restarting the listener without this click is not enough.

The fixed receiver handles the stored payload and prints:

200 order.created ord_test_123 total=4200

Back in Hookspot, confirm that the delivery is now Delivered. Follow the 1 attempt link and confirm its trigger is Manual retry, with your app’s 200 response.

The offline delivery guide documents the same restart-and-retry sequence.

Tell an offline listener from an app error

A stopped listener and a stopped app create different evidence:

• If no listener covers the source, the delivery is Skipped. It has no attempt until you retry it manually.
• If a listener is active but the app is unavailable or returns an error, the delivery is Failed. Its attempts record the app response or forwarding error.

If the listener stayed active while receiver.js stopped, follow the failure and retry steps in the inspection guide. Some error responses also receive system retries, as the retry reference explains.

Check retention and limits

A skipped delivery remains available only while Hookspot retains its request. Hookspot deletes requests after the plan’s retention period, together with their deliveries and attempts. See the maintained retention documentation for the current plan values.

A skipped delivery counts toward monthly usage, while retrying that delivery does not create another counted delivery. The delivery counting documentation keeps those rules current.

On Free, exceeding the monthly delivery limit locks project pages and disables retries, even before the hard limit. The lock lifts when you upgrade to Pro or the month ends.

Hookspot can also reject a new webhook at the hard monthly limit or daily data limit. In those cases it returns 429 and stores nothing, so there is no skipped delivery to recover. Check monthly limits and the daily data limit before assuming every request is retained.

To keep a useful request in your own test suite, follow the fixture export and regression test tutorial.