Skip to content
WebsitePlatform

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.

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

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:

  1. Restart it, or fix what makes it slow. A slow or stopped app is the usual cause.
  2. If your app looks fine, check Status, as a delay on Hookspot’s side can also hold deliveries up.
  3. 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.

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.