Troubleshooting
Find what went wrong with a webhook and how to fix it.
Match the status or symptom you see to a fix below. If the webhook never appeared in Requests, start with Other problems.
Failures and fixes
Section titled “Failures and fixes”| What happened | What to do | Status you see |
|---|---|---|
| No CLI is listening to the source | Start hookspot listen, then retry the delivery. Hookspot does not send it again on its own. |
Skipped with No listener |
| A listener left with deliveries waiting and did not return for at least 5 minutes | Start hookspot listen, then click Retry N skipped on Deliveries. It can repeat webhooks you already received. |
Skipped with No listener |
| You paused or deleted the route, its source or its path while deliveries waited | Resume it and start hookspot listen, then click Retry N skipped on Deliveries. After deleting the route or source, retry each delivery. A delivery whose path you deleted cannot be sent. |
Skipped with No listener |
| A burst went over the listener's soft limit | Wait. The deliveries go out as your app answers. If they crawl, answer the webhook first, then do the slow work. | Pending · Queued |
| Your listener's oldest waiting delivery reached 10 minutes | Check the app your listener forwards to, as Queued deliveries and the backlog email explains. | Pending · Queued, and an email |
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 |
| The CLI stopped before your app answered, or no answer arrived within 30 minutes | Check that hookspot listen is running, then retry the delivery. Hookspot does not send it again on its own. |
Failed |
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 retry the request. | Rejected with No route |
| The source is paused | Click Resume source, then retry the request. | Rejected with Source disabled |
| The request's signature or credentials did not pass the source's verification settings | If the sender is genuine, correct the source's verification settings, such as the secret, then retry the request. | Rejected with Verification failed |
| You retried a delivery, but the member it went to has no CLI listening to its source | Ask that member to start hookspot listen, then retry the delivery. |
Failed |
| The delivery is Delivered, but your app saw nothing | Start the CLI with --forward-to. |
Delivered |
| Your Free organization went over its monthly delivery limit | Upgrade to Pro, or wait for the count to start again on the 1st. Webhooks still reach your app. | Project pages locked |
| Your organization reached its hard limit for the month | 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 |
| Your organization went over its daily data limit | Upgrade to Pro if you are on Free, or wait for the next UTC day. If the data is not yours, delete the source whose URL leaked. | No new requests, and the sender gets 429 |
Queued deliveries and the backlog email
Section titled “Queued deliveries and the backlog email”When a listener’s oldest waiting delivery reaches 10 minutes, Hookspot emails only the member who runs that listener. It usually arrives within 15 minutes of the webhook.
Check the app your listener forwards to, on the machine the email names, then:
- Restart it, or fix what makes it slow. A slow or stopped app is the usual cause.
- If your app looks fine, check Status, as a delay on Hookspot’s side can also hold deliveries up.
- Keep the CLI running, as waiting deliveries go out on their own.
The email’s subject reads Deliveries are waiting for your listener in and the project’s name. The email links to no Hookspot page. It lists:
| Line | What it shows |
|---|---|
| Project | The project’s name. |
| Destination | The path of the listener’s oldest waiting delivery. |
| Queued | The listener’s own waiting deliveries across its destinations, so it can differ from a destination page’s total. Above 1,000, it reads 1,000+. |
| Oldest waiting | How long that delivery has waited. |
| Machine | The listener’s machine, when it has one. |
You get at most one of these emails per project in 24 hours. Another of your machines or destinations that stalls in that project goes unnamed until the next one.
Only deliveries left waiting count. If your CLI reconnects and has room, it takes them and you get no email. If you stop the CLI and do not return, you get no email and they become Skipped.
A locked project’s pages show no backlog. The email still arrives, so you can fix your app without opening a project page.
Other problems
Section titled “Other problems”If a webhook is not in Requests, Hookspot did not store it. It never
reached your webhook URL, or Hookspot answered 405, 413, 429 or 503, 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 a Failed delivery shows “No response received.” and your app answered with a body between about 3.2 MiB and 16 MiB, the body was too large to record. Keep it under 3 MiB, as Deliveries explains.
If the CLI prints an error, Errors in the CLI reference says what to do about it.
If Hookspot does not load, or the CLI or a sender cannot reach it, check Status for an outage.