Author picture Fongang Rodrique

How to Test and Replay Stripe Webhooks Locally

Published · Updated


Stripe provides a powerful suite of APIs and services to facilitate global payment. Its ease of use and payment gateway help process a huge number of transactions over the internet daily.

Webhooks in Stripe allow you to trigger actions in your application when specific events occur on Stripe. However, these triggers and actions can sometimes fail for reasons like timeouts, server overloads, or other unforeseen issues. Monitoring every financial transaction is crucial for the growth and stability of your business.

Hookdeck provides an event gateway that can be used to manage inbound webhooks, including monitoring and replaying webhook events.

🟢 Relaying your Stripe webhooks through Hookdeck makes it easy for you to have a wider view and keep track of all the events that occur.

This guide walks you through connecting a Stripe webhook through Hookdeck to an application running on localhost using the following steps:

  1. Set up a local webhook endpoint
  2. Create a Hookdeck connection
  3. Create a Stripe webhook
  4. Test and retry the webhook event using the Hookdeck Console

1. Set up a local webhook endpoint

For this example, we will use the sample Node.js code from Hookdeck's repository. Feel free to follow up with any application or code you might have.

  1. Open up your terminal and clone the repository by running:
git clone https://github.com/hookdeck/nodejs-webhook-server-example.git
  1. Navigate into the cloned directory and install the dependencies:
cd nodejs-webhook-server-example
npm install
  1. Start the server by executing:
npm run dev

🟢 The node.js server starts on http://localhost:1337. See the list of endpoints in the routes.js file.

We will make use of the /stripe-webhooks-endpoint

2. Create a Hookdeck connection

There are several ways of creating a Hookdeck connection. But for this guide, we're using the Hookdeck CLI without a Hookdeck account, so the CLI will dynamically create a connection.

Create Hookdeck Connection with Hookdeck CLI

  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
      
      
  • Open up your terminal and expose the localhost port with:
hookdeck listen 1337
  • The Hookdeck CLI initiates the creation of a guest account that will be used.
  • You get prompted to do some basic setup:
    • Create a new source label (ex. stripe)
    • Set the path to be forwarded as /stripe-webhooks-endpoint
    • Name the connection label (ex. my-application)
  • The connection is created, and you are given:
    1. A login URL to use for the Hookdeck Console
    2. The webhook URL needed

Stripe Hookdeck connection on terminal

The same connection can be seen on your Hookdeck guest console after following the link. Copy the Stripe Source webhook URL for the next step.

Stripe connection on hookdeck console screenshot

3. Create a Stripe webhook

  • Sign up or log in to your Stripe dashboard.

  • Navigate to Developers > Webhooks and +Add endpoint.

Stripe dashboard screenshot

  • Fill in the details of your webhook.

    • Endpoint URL: Paste the URL copied from the Hookdeck connection created above.
    • Description: A simple description of your webhook endpoint.
    • Select events to listen to: Here, you choose the list of events you want to listen to. For this demo, select Payment Link (payment_link.create, payment_link.updated).
    • Click Add endpoint.

Listen to Stripe events screenshot

After creating the endpoint, it appears on the list of webhooks with an active status.

Stripe active webhook

4. Testing Stripe webhook with Hookdeck

After setting up your local server, configuring the webhooks, and creating a Hookdeck connection to link them, it is time to test the integration.

  • On your Stripe dashboard, click on the Create dropdown at the top right and select Payment link.

Stripe payment link screenshot

  • Create or select any product you have and Create link. This action will trigger the payment_link.create event, which Hookdeck will relay to your application.

Stripe create link screenshot

  • Check the Hookdeck Console for a successful request with a 200 status code.

Hookdeck console 200 success

Back on the terminal of the localhost project, the payload is printed like below:

localhost project terminal payload

Retrying error or failed events

In case there are any failed events that don’t make it to your destination, Hookdeck provides you with the ability to retry and attempt to deliver any failed or error event.

To retry a failed event:

  • Click on the Retry icon by the right of the failed event

Failed Stripe Event

For more details on managing Hookdeck events, refer to the Hookdeck documentation.

Conclusion

In this tutorial, you learned how to receive Stripe webhook events to an application running on localhost using the Hookdeck CLI and Hookdeck Console.

If you found this helpful, try out the Hookdeck platform that helps you safely consume, monitor, and troubleshoot your Stripe webhooks in development and production, ensuring seamless operation and transaction tracking for your business.