Troubleshooting

Find what you see in the table below and do what it says. If it is not there, read the cases after it.

Failures and fixes

What happened	What to do	Status you see
The CLI is not running	Start hookspot listen, then retry the delivery. Hookspot does not send it again on its own.	Skipped with CLI offline
Your app answers 408, 429 or 5xx, or cannot be reached	Fix your app. Hookspot tries again on its own.	Failed, with System retry attempts
Your app answers another 4xx, such as 400	Fix your handler, then retry the delivery. Hookspot does not retry it.	Failed
The source has no route, or its routes or their paths are paused	Create a route, or resume the route or its path, then replay the request.	Rejected with No route
The source is paused	Click Resume source, then replay the request.	Rejected with Source disabled
The delivery is Delivered, but your app saw nothing	Start the CLI with --forward-to.	Delivered
Your organization reached twice its monthly request limit	Upgrade to Pro if you are on Free, or wait for the count to start again on the 1st.	No new requests, and the sender gets 429

Other problems

If a webhook is not in Requests, Hookspot did not store it. It never reached your webhook URL, or Hookspot answered 405, 406 or 429, as Responses lists.

To check the URL, click the source’s card on Routes and copy its Webhook URL into the sender’s settings again. Then click Send test request on Overview to check the rest of the path.

If the sender gets 405, no source has that webhook URL. A deleted source’s URL stops working for good, so give the sender the URL of a current source.

If your app answers 404, check the route’s path and the --forward-to address, as Forward to your app shows.

If the CLI shows refused for a request, nothing listens on the port in --forward-to. Start your app or fix the port. Hookspot records 502 and tries again.

If your app takes more than 30 seconds to answer, the CLI stops waiting and Hookspot records 502. Answer the webhook first, then do the slow work.

If the CLI prints an error, Errors in the CLI reference says what to do about it.