12/13/2023 | Press release | Distributed by Public on 12/13/2023 07:28
Consume and test webhooks in your local development environment
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.
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:
Adyen Postman Collection for webhooks
Tunneling software
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.
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
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 ✅
Cons ❌
Easy to use with many different examples
Flexible (can edit JSON payloads as needed)
No need to expose a public endpoint
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.
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.
This option can be used throughout the development and testing of the integration.
Pros ✅
Cons ❌
Receive webhooks sent by Adyen platform
Requires 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.
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)
This approach might be suitable during testing and validation phases, later in the development lifecycle.
Pros ✅
Cons ❌
Receive webhooks sent by Adyen platform
Source code can be tested and modified directly on Gitpod
Requires 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.
Consuming webhooks blog and video
Webhooks on Adyen docs
Adyen Postman collections video
Make the right decisions with the latest insights and advice on business growth and payments innovation.
By submitting your information you confirm that you have read Adyen's Privacy Policy and agree to the use of your data in all Adyen communications.