Test Webhooks Locally with Hookdeck CLI

Developing and testing webhooks can be challenging because webhook providers like Stripe, Shopify, or GitHub require a publicly accessible HTTPS URL to deliver events. This requirement conflicts with typical local development environments, which run on non-public addresses like http://localhost:3000.

The Hookdeck CLI provides a listen command that creates a secure tunnel from a public Hookdeck URL directly to your local machine. This allows you to receive real webhook payloads on your development server, enabling rapid iteration, debugging with actual data, and comprehensive testing without deploying your application.

Prerequisites

Before you begin, ensure you have the following:

  • A Hookdeck account (the free tier is sufficient).
  • Node.js and npm or yarn installed on your machine.
  • The Hookdeck CLI installed.
      npm install hookdeck-cli -g
  
  
      yarn global add hookdeck-cli
  
  
        brew install hookdeck/hookdeck/hookdeck
    
    
    1.     scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
    
    
    2.   scoop install hookdeck

    1. Download the latest release's tar.gz file. 

    2.     tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
    
    
    3.   ./hookdeck
  • Your local web application or server is running and listening for requests on a specific port (e.g., http://localhost:4000).

Step 1: Run hookdeck listen to Start a Session

The hookdeck listen command dynamically creates a Connection between a Source and a Destination of type "CLI". The behavior of the command changes depending on whether the specified source already exists.

  1. Open your terminal.

  2. Run the listen command with your local port and a name for your source. For this example, we'll use stripe-webhooks as our source name.

    hookdeck listen 4000 stripe-webhooks
    • 4000: The port your local server is listening on.
    • stripe-webhooks: A unique name for the source.

    If the stripe-webhooks source does not exist: A new source with this name will be created. The CLI then automatically creates a new connection that links this source to a "CLI" destination, forwarding events to http://localhost:4000.

    If the stripe-webhooks source already exists: The CLI will use the existing source. It will then look for a connection that already links this source to a "CLI" destination. If found, it will use that connection. If not, it will create a new connection for the session.

The CLI will then establish the session and output the public Event URL for your source:

Dashboard
👉 Inspect and replay webhooks: https://dashboard.hookdeck.io/cli/events

stripe-webhooks
🔌 Event URL: https://hkdk.events/src_xxxxxxxx

Step 2: Configure the Third-Party Webhook Provider

Now, instruct the third-party service to send its webhooks to your new public Hookdeck URL.

  1. Go to the webhook settings page of the third-party service (for example, in the Stripe Dashboard, this is under Developers > Webhooks).
  2. Add a new webhook endpoint.
  3. Paste the Event URL from the CLI output (e.g., https://hkdk.events/src_xxxxxxxx) into the "Endpoint URL" field.
  4. Select the specific events you want the provider to send.
  5. If the provider uses a signing secret, copy it. You can add this to your Hookdeck source's verification settings in the Hookdeck Dashboard for added security.

Step 3: Trigger and Test Webhooks

With the tunnel active, you can now test your integration.

  1. Perform an action in the third-party service that triggers a webhook (e.g., create a test payment in Stripe).
  2. Observe the results:
    • Hookdeck CLI Output: Your terminal will log the incoming webhook.
    • Your Local Application Logs: Your local server should receive the request. Check its console output.
    • Debugger: Because the code is running locally, you can set breakpoints in your IDE to step through the webhook handling logic in real-time.

Using the CLI without Logging In

If you run hookdeck listen without first running hookdeck login, the CLI will create a temporary Guest Account for you.

  • You can still receive webhooks locally.
  • However, you will not be able to see the connection, source, or Events in the main Hookdeck Dashboard. You can only view them in the temporary CLI session console.
  • Logging in with hookdeck login ensures that all your testing data is saved to your account for later inspection and replay.

Advanced hookdeck listen Options

The listen command has a few powerful flags for more advanced use cases:

  • <connection-query>: Filter which connections are used. You can provide the name of a connection or the path of the destination (e.g., /webhooks/stripe).
    hookdeck listen 4000 my-source-name /webhooks/stripe
  • --path: Specify a path to append to your localhost URL. For example, --path /my-handler will forward events to http://localhost:4000/my-handler.
    hookdeck listen 4000 my-source-name --path /my-handler

For a full list of commands and flags, refer to the CLI documentation.

Troubleshooting Tips

  • Webhooks appear in Hookdeck but not locally:
    • Verify the port number in your listen command is correct.
    • Ensure your local server is running and listening on that exact port.
  • 404 errors on your local server: If you are using the --path flag, ensure the path matches a route defined in your local application.

Conclusion

The Hookdeck CLI listen command simplifies local webhook development by providing a public URL that tunnels requests to your local machine. It dynamically manages the necessary Sources and Connections , allowing you to focus on building and debugging your webhook integration with real-time data. This accelerates the development cycle and improves the reliability of your webhook handling logic.

Related Hookdeck Features & Documentation

Configuring Hookdeck Sources ->

Understanding your public webhook URLs.

Working with Connections ->

For more advanced local testing setups.

<- Previous Test Outbound Webhook Delivery Next -> Transform Event Payload Content-Type (e.g., x-www-form-urlencoded to JSON)