Forwarding to a destination

A destination is where Inspect forwards the requests a Source URL captures. Adding one means requests are captured and delivered, so you also see the response your endpoint returned.

Without one Inspect still captures everything, but the Forward tab has no response to show because nothing was delivered anywhere.

Each Source URL has one destination. Set it up from the Forward tab of any request, choosing Localhost or HTTP. From then on, every new request is delivered as it arrives. Requests captured before that are forwarded one at a time, when you open their Forward tab.

Forwarding to an HTTP URL

Choose HTTP and enter the Destination URL that should receive the requests. Any publicly reachable http or https endpoint works, including a staging deployment or a preview URL. Source URLs aren't accepted, so a Source URL can't forward to itself.

Each forwarded request shows the status your endpoint returned in the request list, so a 500 from your handler is visible immediately alongside the payload that caused it.

Forward to endpoints you're developing against, not production ones. Inspect forwarding has no automatic retries, no filtering, and no access control, and anyone with the Source URL can send requests through it. For production traffic, use an Event Gateway project.

Forwarding to localhost

A local server has no public URL, which is the whole reason webhook development is awkward. The Hookdeck CLI solves it by forwarding captured requests to a port on your machine.

Choose Localhost. Inspect shows two steps: installing the CLI, and a command to start it with the port and path your server listens on (3000 and /webhooks unless you change them). The command looks like this:

hookdeck listen 3000 <your-source-name> --path /webhooks --cli-key <cli_key>

If you don't have the CLI yet, install it:

  npm install hookdeck-cli -g
  
  

  yarn global add hookdeck-cli
  
  

    brew install hookdeck
    
    

Or run it with no install by putting npx hookdeck-cli in place of hookdeck. That's the form the Inspect API hands back, in the cmd_hint field of a new Source URL.

--cli-key connects the command to your Source URLs, so there's nothing else to set up, and the same command works unchanged in CI. Treat the key as a secret: anyone with it can listen to your Source URL and forward its requests.

Passing --cli-key to listen needs CLI v2.4.0 or later. If the machine has no existing Hookdeck login, the first run saves the key and later runs can drop the flag. If you're already logged in, the key applies to that run only and your stored login is left untouched, so pass it each time.

The CLI adds the path a request was sent to onto --path. Give the provider the bare ingest URL: a request sent to <ingest_url>/webhooks with --path /webhooks reaches your server at /webhooks/webhooks.

Inspect shows a Connected badge once the CLI is listening, and Not connected when it isn't. Requests captured while you're disconnected are still recorded, so you can forward or retry them once you reconnect.

For the full command reference, see the CLI documentation.

Retries, filters, and transformations

Inspect destinations exist to close the loop while you're building. They have no retry policy, no filters, and no transformations.

Those are Event Gateway features. To use them, sign up for a Hookdeck account if you don't have one, then create an Event Gateway project. There, a connection routes a source to a destination and adds retries, filters, and transformations.