How Hookspot works

Hookspot receives each webhook at a webhook URL, stores it, and forwards it through the CLI to the app on your machine. This page follows one webhook along that path.

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.
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.

Sources

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.

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.

Routes

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.

Requests

A request is one webhook as the source received it: 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. After you fix the cause of a Rejected request, click Replay to route the same request again.

Hookspot keeps requests for your plan’s retention period.

Deliveries

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 the request arrives gets its own delivery, with its own answer, status and retries. Hookspot records your app’s status, headers and body, or 502 if the CLI cannot reach your app.

If the source has no listener, each route gets one Skipped delivery with CLI offline 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.

Retries

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.

Retry on a delivery sends it again. 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 had 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.

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