How to Test and Replay Paddle Webhooks Events on localhost with Hookdeck

Paddle provides a simple international payment and banking infrastructure for handling business payments, taxes, and subscriptions. Paddle’s all-in-one payment solution handles all payments and can integrate with multiple payment processors. This makes it possible to have just a single integration that accepts multiple payment methods with multiple currencies.

The Paddle developer portal and sandbox make available a set of tools to use in configuring and integrating Paddle with your solutions.

Hookdeck offers a simple infrastructure to safely receive, monitor, and replay your webhooks.

Relaying your Paddle webhooks through Hookdeck provides an overall view and keeps track of every event that occurs.

In this guide, I’ll show you how to connect Paddle webhooks through Hookdeck to an application running on localhost. We will cover:

1. How to set up a localhost webhook endpoint
2. How to create a Hookdeck connection
3. How to create a Paddle webhook event listener
4. How to test a Paddle webhook event with localhost app

Set up a localhost webhook endpoint

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

• Open up your terminal and clone the repository by running

git clone https://github.com/hookdeck/nodejs-webhook-server-example.git

• Change into the cloned directory and install the dependencies

cd nodejs-webhook-server-example
npm install

• Start the server by executing:

node server.js

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

We will make use of the /paddle-webhooks-endpoint.

Create Hookdeck Connection

There are several ways of creating a Hookdeck connection (see the guide here).

Create Hookdeck Connection with Hookdeck CLI

• Install the Hookdeck CLI
• 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 (ex. paddle)
  • Set the path to be forwarded to as /paddle-webhooks-endpoint
  • Name the connection label (ex. localhost-app)
• The connection is created and you are given
  1. A login URL to use for your Hookdeck dashboard
  2. The webhook URL needed

• The same connection can be seen on your Hookdeck online dashboard after following the link.

• Copy the Paddle Source webhook URL. It will be used later in setting up the Paddle webhook listener.

Create a Paddle webhook event listener

• Sign up or log in to the Paddle developer sandbox
• Navigate to Developer Tools > Event on the side panel

• Scroll down and fill in Webhook URL with the source URL copied from Hookdeck
• Select the box across the webhook for the Subscription Created event and Save Changes

This will create a webhook listener that is subscribed to the Subscription Created webhook event on Paddle and will be triggered each time a new subscription is created.

Test Paddle webhook events

It should be noted that Paddle sends its webhook payload with application/x-www-form-urlencoded as content type. Incoming payloads in other formats can easily be converted to a json payload or payload of any format using Hookdeck Transformations. See how to format using the querystring node package here.

We have successfully set up our local server, created a Hookdeck connection, and configured a Paddle webhook listener. Let us test and trigger the event specified to make sure it is being received in our localhost application.

Paddle provides a Webhook Simulator that can be used for testing purposes.

Since we created a webhook listener already, let us go ahead and see how it can be triggered in a real-life scenario.

• On your Paddle sandbox dashboard, navigate to Catalog > Subscription Plans
• A list of your existing subscription plans is shown if you have any. Click Create Plan to create a new plan

• Configure details for the subscription plan and Save Plan

• The newly created plan is seen on the Subscription Plan list
• Click on the menu icon across it then Checkout Link to copy the checkout link

• Open the link on a new browser tab and proceed with the subscription
• For the payment details, Paddle provides a list of test payment cards that can be used

• Upon a successful subscription, the Subscription Created event is triggered which is then relayed by Hookdeck directly to your localhost application
• On your Hookdeck Request dashboard, filter the request sources to Paddle (you should see the requests received with a 200 status code)

• Back in the terminal of the localhost application, the successful payload from the webhook is received and logged

Retrying error or failed events

In case there are any failed events that don’t make it to your destination for some reason, Hookdeck provides an ability for you to retry any attempts to deliver any failed or error event.

To retry a failed event:

• Navigate to the Events tab on the sidebar of your connection and filter as per your Destination, then hit the Retry across the failed event

• This will replay the event again from Hookdeck to the local application

A Hookdeck Request is an incoming webhook that Hookdeck receives from an external source. It contains the data that was sent by the external source as is (ex. from Paddle).

A Hookdeck Event is the webhook delivered by Hookdeck including configurations or filters applied to a destination (ex. to localhost app).

See more details on managing Hookdeck requests and events on the Hookdeck documentation.

In this tutorial, you have learned how to receive Paddle webhook events through Hookdeck, a reliable webhook provisioning platform, to an application running on localhost.

Hookdeck can be used safely to consume, monitor, and troubleshoot your Paddle webhooks.