Developer’s Guide: working with webhooks on your localhost

In this Developer Guide you will learn how to consume and test webhooks in your local development environment. You will also understand the different advantages and disadvantages associated with the options we recommend.

Introduction

Webhooks are an essential feature of the Adyen platform. They deliver events like payment outcome, new chargebacks, availability of a report, updates on merchant onboarding, and so on, and therefore it is important to ensure they can be received, consumed and tested during the development of your specific Adyen integration.

While inspecting the content of a webhook payload can be useful (for example by forwarding the webhook to tools like webhook.site), developers also require the capability to receive incoming webhooks directly in the application running on their laptop. It is a matter of more effective testing that verifies the correct processing on the incoming events and the associated workflow that follows.

During the development of the application there are many changes to implement and many assumptions to confirm. The flexibility of working in the local environment is therefore crucial for both developer’s experience and productivity.

This developer guide explores the following options:

1. Adyen Postman Collection for webhooks
2. Tunneling software
3. Using a Cloud Development Environment (CDE)

Postman Collections

Visit the AdyenDev Postman space and fork the Adyen Webhooks collection. It includes several examples of the different types of webhooks.
Each example provides the JSON payload with the event code and any other applicable field.
The HMAC signature is calculated ‘on-the-fly’ and included in the HTTP request.

HowTo

• Fork the collection
• Configure the environment variables:

1. Webhook url (default http://localhost:8080)
2. HMAC key (same as configured in your application)
3. Additional settings depending on your integration (Merchant Account for payments, Balance Platform Id for Platforms, etc..)

• Send the requests to your application

When to use it

This is highly convenient in the initial development phase of the integration: developers want to quickly test the processing of the different JSON payloads that will be delivered by Adyen.

Pros ✅: easy to use with many different examples, flexible (can edit JSON payloads as needed), no need to expose a public endpoint
Cons ❌: not a real integration with Adyen backend

Tunneling Software

Tunneling software tools such as ngrok and Microsoft Dev Tunnels can be used to expose your local environment to the internet. These tools essentially create a temporary connection between your local machine and a public endpoint, hosted by the company providing the tool.

By establishing these tunnels you can:

• Allow remote testing and collaboration
• Run demos using your local application
• Consume webhooks originated by a platform or third-party application, making webhook testing a lot simpler.

Below you can see how to test the webhook using ngrok, however the same approach applies when using a similar tool.

HowTo with ngrok

• Install ngrok
• Start ngrok ngrok http 8080
• Copy the ngrok generated URL for https
• Create/update Adyen webhook with the ngrok URL
• Ensure the HMAC key for the webhook is used by the application on your localhost
• Trigger a webhook: perform a payment or use Test Webhook function available in the Customer Area Note: when restarting ngrok a new URL is generated, therefore the Adyen webhook URL must also be updated. When to use it This option can be used throughout the development and testing of the integration.

Pros ✅: receive webhooks sent by Adyen platform
Cons ❌: requires exposing localhost to the Internet

Cloud Development Environment (CDE)

A Cloud Development Environment (CDE) is an online development environment that allows developers to write, test, and deploy code from a web browser. It provides developers with the necessary tools to build and test software, without setting up and maintaining a local infrastructure (tech stack and all dependencies).
As the development environment is hosted in a public cloud-based platform, it provides a convenient way to test webhooks.

There are several CDEs (Gitpod, GitHub Codespaces, Codeanywhere, etc..). Choose your preferred tool, deploy your application source code and make it reachable by Adyen.

Below you can see how to test the webhook using Gitpod (all Adyen sample applications can be deployed on Gitpod), however a similar approach applies when using a different CDE.

HowTo on Gitpod

• Configure the necessary settings (API key, merchant account, HMAC key) as Gitpod environment variables
• Deploy the application on Gitpod
• Copy the Gitpod generated URL (note: not the Gitpod workspace URL but the URL of the web application running on Gitpod)
• Create a webhook using the generated Gitpod URL as well as the path to access the webhook handler (ie https://abcd1234.gitpod.io/api/webhooks/notifications by default)
• Generate the HMAC key for the webhook and copy it
• In the Gitpod terminal stop the application
• Set the HMAC KEY as env variable gp env ADYEN_HMAC_KEY=ASDEW##############
• Update the environment variables for the terminal session eval $(gp env -e) Restart the application in the terminal (or recreate the Gitpod workpace)

When to use it

This approach might be suitable during testing and validation phases, later in the development lifecycle.

Pros ✅: receive webhooks sent by Adyen platform, source code can be tested and modified directly on Gitpod
Cons ❌: requires using cloud service, it must follow closely the “HowTo” steps (for example the Gitpod URL must be generated before configuring the webhook)

Conclusion

Webhooks are a critical component of Adyen’s platform, and testing them effectively during development is essential.

The ability to receive and process webhooks locally greatly enhances developer productivity. We’ve explored three options, each with its own advantages and limitations: Adyen Postman Collections for quick testing, tunneling software for ongoing development, and Gitpod for more comprehensive testing.

Choose the approach that fits best with your needs, requirements and development methodology, and reach out to let us know what works for you and how we can help you further.