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

Author picture Rodriq Jaro

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

Published · Updated


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

Paddle event Hookdeck CLI

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

Hookdeck dashboard connections Paddle

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

Create a Paddle webhook event listener

Paddle Events Dashboard

  • 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

Subscription created webhook event on Paddle

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

Subscription plans Paddle sandbox dashboard

  • Configure details for the subscription plan and Save Plan

Create new plan Paddle sandbox dashboard

  • 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

Checkout link Paddle sandbox dashboard

Paddle subscription screenshot

  • 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)

Hookdeck dashboard Paddle event received

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

Paddle webhook received on localhost

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

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