Webhooks

Webhooks are crucial for a successful integration with Adyen, and the only way you'll receive automatic updates about:

• Events that are not triggered by a request from your side, for example when a shopper initiated a chargeback, or when a new report becomes available.
• Requests that are processed asynchronously. For example, for many local payment methods such as iDEAL, the outcome of a payment request might take several hours to confirm. After we know whether the payment was successful, we send you a webhook event to inform you of this.

You can use webhooks to automate business processes, for example order management or downloading reports for accounting.

To manage webhooks, you must have the following user role:

• Merchant technical integrator

To process webhooks, you need to:

1. Expose an endpoint on your server.
2. Set up webhooks in your Customer Area.
3. Accept webhook events.

Step 1: Expose an endpoint on your server

Webhooks are HTTP callbacks sent to an endpoint on your server. Adyen requires you to use HTTPS endpoints with TLSv1.2 or TLSv1.3.

To receive webhook events, you need a server that has the following:

• An endpoint that can receive a JSON or a SOAP call, or an HTTP POST.
• For test environments: an open TCP port for HTTP traffic (must be 80, 8080, or 8888) or HTTPS traffic (must be 443, 8443, or 8843) with TLSv1.2 or TLSv1.3.
• For live environments: an open TCP port for HTTPS traffic (must be 443, 8443, or 8843) with TLSv1.2 or TLSv1.3.
• A username and password for basic authentication.
  You need to enter these in your Customer Area in Step 3.

Depending on your network and security requirements, you might also need to add our network to your firewall's allowlist.

Step 2: Set up webhooks in your Customer Area

In your Customer Area, enable and configure webhooks for your company account, merchant account, and merchant account groups. However, we recommend to configure webhooks for your company account. To set up a webhook for a specific merchant account, create a webhook for your company account, and configure merchant accounts for that webhook.

• You can configure Payments webhooks on the company, merchant account, and merchant account groups.
• You can configure Balance Platform webhooks on the company account level only.

To configure a webhook:

1. In your Customer Area, go to Developers > Webhooks.
   If you have a Balance Platform integration, select Payments or Platforms to view the webhooks available to you based on your integration.

2. Select Create new webhook.
   If you are adding a webhook for your platform and have multiple platforms set up to run on Adyen, select the balance platform where you want to configure your new webhook.

3. From the list of webhooks, select Add for the one to add.

4. Under General, configure the following:

   Setting	Description
   Enabled	Select the toggle to enable or disable the webhook.
   Version	The webhook version.
   Description	Your description of the webhook.
   Merchant accounts	You can apply the webhook to all merchant accounts for a company account, include only specific merchant accounts, or exclude specific merchant accounts for your company account.

5. Under Server configuration, configure the following:

   Setting	Description
   URL	Your webhook server's URL. It must be a public URL.
   Method	JSON, HTTP POST, or SOAP
   Encryption protocol	TLSv1.2 or TLSv1.3

6. Under Security, configure the following:

   Setting	Description
   Basic authentication	Enter your server's username and password.
   HMAC Key	Generate a new HMAC Key or use an existing HMAC key.

7. Under Events settings, select the event codes for this webhook. Some webhook types do not support more than one event code, so this setting does not appear.

8. If the Additional settings section is available, optionally select the additional information you want to receive in this webhook. Some webhook types do not support more than one event code, so this section does not appear.

9. Select Save configuration.

Step 3: Accept webhooks

When we deliver a webhook event to your server:

1. Verify the HMAC signature included in the webhook event payload.
   This is to confirm that the webhook event was sent by Adyen, and was not modified during transmission. For more information, refer to Verify HMAC signatures. If the HMAC signature is not valid, we do not recommend acknowledging the webhook event.
2. Store the webhook event in your database.
3. Acknowledge the webhook event with a successful HTTP response status code, for example 202.
   If an error occurs, we recommend that your server respond with an error HTTP response status code.
4. Apply your business logic.
   Make sure that you acknowledge the webhook event before you apply any business logic, because an error in your business logic can prevent webhooks with important updates from reaching your system.

For information about the structure and content of webhooks, refer to Webhook structure and types.

Step 4: Test and go live

Test your webhooks server

Your server must acknowledge webhooks with a successful HTTP response status code (like 202).

1. Log in to your Customer Area.
2. Select Developers > Webhooks.
3. Select the webhook to test.
   The Webhook details panel includes information about the configuration. Under Events, you can find the configured event codes that you can test for this webhook.
4. Select the edit icon
5. Select Test configuration.
6. If you are on a company account, select a Merchant account from the dropdown list.
7. In the Event dropdown list, select the event code to test webhooks for.

If the test webhook failed, you get an error message with the reason. Troubleshoot the problem.

End-to-end testing

We recommend you create a test payment and test the webhooks associated with it. Match the test payment to a webhook with the pspReference or merchantReference in the payload of the webhook.

Go live

1. Follow the instructions in Step 2 to set up webhooks in your live Customer Area.
2. Test webhooks in your live Customer Area.
3. If you are verifying HMAC signatures, make sure that you use the HMAC key from your live Customer Area, which is different from the HMAC key from your test Customer Area.