How to Test PayPal Webhook Events on localhost with Hookdeck

PayPal is a safe and secure online payment system that enables users to pay for purchases, accept payments when selling goods or services, and send money to friends and family.

As a developer, you can use the PayPal developer portal to integrate and build payment solutions using PayPal.

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

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

In this guide, I’ll show you how to connect PayPal webhooks through Hookdeck to an application running on localhost using the steps outlined below.

1. Set up a localhost webhook endpoint.
2. Create a Hookdeck Connection.
3. Create a PayPal app and webhook.
4. Test PayPal webhook event to localhost app.

Setting 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 /paypal-webhooks-endpoint.

Create a Hookdeck Connection

There are several ways of creating a Hookdeck Connection. For our guide to Connections, click 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. paypal).
  • Set the path to be forwarded to as /paypal-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; and
  2. The webhook URL needed.

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

• Copy the PayPal Source webhook URL. It will be used later when creating the PayPal application and webhook.

Creating a PayPal app and webhook

• Sign up or log in to your PayPal Developer Dashboard.
• Navigate to My Apps & Credentials on the sidebar.
• Click to open the default app provided by PayPal or use any existing app you may have.

🔵 You will need to use Live credentials for applications in production.

• Add Webhook to create a new webhook.

• Fill in the Webhook URL with the URL you copied from Hookdeck and select Billing plan created as an event to listen to, then Save.

The webhook is successfully created.

Using PayPal’s Webhook Simulator to test webhook events

We have successfully set up our local server, created a Hookdeck Connection, and configured a PayPal webhook.

With the PayPal Webhook Simulator, we are going to simulate webhook events and see how this gets relayed through Hookdeck to our local application.

🔵 Note that the Webhook Simulator functions independently of the webhook event created on any PayPal app.

• Go to the Webhook Simulator tab.
• Fill in the Webhook URL copied from Hookdeck, then select the event to trigger and Send Test.

• After creating, the Billing plan 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 PayPal. You should see the requests received with a 200 status code.

🔵 Hookdeck provides a reliable uptime webhook endpoint and queues all incoming webhook requests that can be modified and replayed.

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

Retrying error or failed events

In case there are any failed events that don’t make it to your destination, Hookdeck give you the ability 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.
• Click on the Kebab menu by the right of the failed event, then Retry.

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

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

In this tutorial, you have learned how to receive PayPal 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 PayPal webhooks.