Developer’s Guide: working with webhooks on your localhost

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)

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:

  • Webhook url (default http )

  • HMAC key (same as configured in your application

  • 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 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 consume (on your localhost) 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 ❌: Require exposing localhost to the Internet

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 (for example https://########.gitpod.io/api/webhooks/notifications)

• 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 ❌: Require using cloud service, must follow closely the HowTo steps (Gitpod URL must be generated before configuring the webhook)

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 validation and integration testing. 

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

References

Consuming webhooks blog and video

Webhooks on Adyen docs

Adyen Postman collections video