Skip to content
WebsitePlatform

How Hookspot works

Follow one webhook from your webhook URL to the app on your machine.

Hookspot receives webhooks at your webhook URL, saves them and forwards them through the CLI to the app on your machine. Follow a request below to see where to inspect it and how to send it again.

  1. A sender posts to your webhook URL. The sender is the service that sends the webhook. Hookspot stores the request and answers the sender.
  2. Hookspot routes the request. Each route gets one delivery for each CLI listening to the source, or one Skipped delivery while none does.
  3. The CLI receives each delivery. hookspot listen must be listening to the source. Above a soft limit, a delivery waits its turn.
  4. The CLI forwards it to your app. Forward to your app shows the address your app gets.
  5. Hookspot records what your app answered. A 2xx status makes the delivery Delivered. Any other status makes it Failed.

A source is a named webhook URL that a sender posts to. You name it in the New route dialog, and Hookspot creates its URL.

Webhook URL lists what the URL accepts and how Hookspot answers the sender. To send your own answer, see Reply to the sender.

A source can verify its senders. Hookspot then rejects a webhook without a valid signature or credentials, and never delivers it.

Pause source on the source’s page keeps its URL working. Hookspot still stores each request, but marks it Rejected with Source disabled and delivers nothing.

A route connects a source to a path in your local app, such as /webhooks. You create one in the New route dialog from a source and a Path in your local app.

A source can have several routes, one per path, as Send one webhook to several paths shows.

If a source has no route, or all of its routes or their paths are paused, Hookspot marks its requests Rejected with No route.

A request is the webhook Hookspot received, including its method, URL, headers, query and body. Requests lists each one with its Outcome: Delivered, Failed, Skipped or Rejected.

A request with several deliveries shows the worst outcome among them, so one Failed delivery makes the request Failed. To send a request through your routes again, retry or replay it.

Hookspot keeps requests for your plan’s retention period.

Hookspot answers the sender without waiting for routing. Under heavy load or during an outage, routing can run minutes or longer after the sender gets its 200.

If your app checks how old a signature is, for example through the sender’s SDK, it may reject a late delivery. Have the sender send the webhook again to get a new signature. Retry and Replay keep the old one.

A delivery is one request on its way along one route to one listener, a running hookspot listen. Each send is an attempt.

Every listener of the source when Hookspot routes the request gets its own delivery, with its own answer, status and retries. A listener that joins after routing gets no delivery of its own from it. Hookspot records your app’s status, headers and body, or 502 if the CLI cannot reach your app.

Hookspot records up to 3 MiB of your app’s response body:

Your app’s body Hookspot records
Up to 3 MiB The whole body
Over 3 MiB, up to about 3.2 MiB The first 3 MiB
Over about 3.2 MiB, up to 16 MiB Nothing. The CLI’s connection closes, and the delivery fails within 10 minutes.
Over 16 MiB 502, as the CLI sends no body

If the source has no listener, each route gets one Skipped delivery with No listener and no attempt. Hookspot does not send it again on its own. Start the CLI, then click Retry delivery.

Run several listeners shows how several CLIs share a project.

A delivery waits when its listener is at its soft limit of 50 buffered deliveries. A buffered delivery reads Pending · Sent, as Hookspot sent it to the CLI and your app has not answered yet. A few over 50 can go out at once.

Deliveries above the limit read Pending · Queued. They wait and go out as the listener answers, usually oldest first. Each listener has its own limit, so another member’s backlog does not use up yours.

If 1,000 webhooks reach a listener whose app takes 1 second to answer each, 50 go out at once. The other 950 follow at about one a second. Handle a burst shows how to watch this.

A delivery keeps waiting while its listener keeps listening and its route delivers, up to your plan’s retention period. Retry on a delivery and Hookspot’s own retries ignore the limit.

A listener leaves when its CLI stops or its network drops. If it reconnects, it keeps its waiting deliveries. The same member must run the new hookspot listen on the same machine, with the same --forward-to address, listening to the source.

If no such listener returns, its waiting deliveries become Skipped with No listener after at least 5 minutes. A long backlog can take longer. Retry N skipped sends them to the member who clicks it.

A delivery the CLI already has stays with that listener, as your app may already have it. Hookspot does not send it again on its own. It becomes Failed at least 5 minutes after Hookspot sent it, and you can retry it.

Handle a burst walks through a listener leaving.

Pausing a route, its source or its path stops new deliveries through it and holds nothing for later. Resuming does not send the webhooks that arrived during the pause.

Deliveries still waiting when you pause become Skipped with No listener as their turn comes. After you resume, Retry N skipped sends them. Deleting the route skips them too, and N does not count those.

Deliveries whose turn has not come when you resume still go out. A delivery the CLI already has still reaches your app. Handle a burst walks through a pause.

Hookspot still stores a webhook that arrives during a pause. If every route was paused, retry the Rejected request after you resume. If another route kept delivering, only Replay sends it, and that other route gets it again.

Hookspot tries a delivery again when the answer is 408, 429 or a 5xx status. It waits longer before each retry and stops at five attempts. If you pause or delete the route, its source or its path, Hookspot stops retrying, and the delivery stays Failed.

Retry on a delivery sends it again, even if you paused or changed its route in the meantime. The Attempts tab lists every attempt with its own response and its trigger: Initial, System retry or Manual retry.

A retry goes to the delivery’s listener. If that listener stopped, the retry goes to the newest listener the same member runs on the source. If the member has none left, the delivery is Failed.

A Skipped delivery has no listener, so a retry sends it to your newest listener of its source. Without one, it stays Skipped.

Retry N skipped on Deliveries retries every skipped delivery whose source your CLIs listen to. A delivery whose route, source or path you paused or deleted stays Skipped. N does not count it.

The deliveries you retry go out as your listeners have room. Each stays Skipped until it goes out. If you stop your listeners first, the rest stay Skipped until you click again.

If you can retry and listen, N counts what your click would send. Otherwise it counts the project’s:

You N counts The banner on Deliveries shows
Can retry, listening to every source The project’s skipped deliveries Retry N skipped
Can retry, listening to some sources Those sources’ skipped deliveries Retry N skipped, or no banner when N is 0
Can retry, not listening The project’s skipped deliveries A disabled button and a hint to start the CLI
A viewer, who cannot retry The project’s skipped deliveries The count, with no button or hint

N falls as those deliveries go out. It also updates without a reload when you start or stop a listener.

If you listen only to source B, with 2 skipped on B and 1,000 on A, the button reads Retry 2 skipped and sends those 2. With none on B you see no banner. The 1,000 still list as Skipped, so you can ask a member who listens to A to retry them.

Retry N skipped can repeat webhooks you already received, and the banner’s hint says so. A skipped delivery does not record whom it missed, so the click sends all of them to you. If another member’s listener left, you get its skipped deliveries even when your own listener received those webhooks.

To send a request to your app again from the CLI, see Replay a request.