---
title: "Configure and manage webhooks"
description: "Learn how to configure and manage subscriptions to Adyen webhooks."
url: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage"
source_url: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage.md"
canonical: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage"
last_modified: "2026-06-01T15:33:16+02:00"
language: "en"
---

# Configure and manage webhooks

Learn how to configure and manage subscriptions to Adyen webhooks.

[View source](/development-resources/webhooks/configure-and-manage.md)

You can configure webhook subscriptions for your [company account](/account/account-structure/#company-account), [merchant account](/account/account-structure/#merchant-accounts), and [merchant account groups](/account/account-structure#account-groups).

We strongly recommend that you configure your webhook subscriptions on the company account level. To configure a webhook subscription for a specific merchant account, create a webhook for your company account, and [configure merchant accounts](#configuring-merchant-accounts) to include or exclude specific merchant accounts from that webhook subscription. This ensures that you do not have duplicate webhook configurations, and improves performance.

For improved performance, we also recommend that you limit the number of webhooks you configure for each company account.

## Requirements

Before you begin to configure and manage webhooks, take into account the following requirements and preparations.

| Requirement                                    | Description                                                                                                       |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Integration type**                           | All integrations.                                                                                                 |
| **[Customer Area roles](/account/user-roles)** | Make sure that you have one of the following roles- **Merchant admin**
- **Merchant technical integrator**        |
| **Setup steps**                                | Before you begin:- Read the section on [securing your webhooks](/development-resources/webhooks/secure-webhooks). |

## How it works

To process webhooks, you need to:

1. [Expose an endpoint on your server](#expose-an-endpoint-on-your-server).
2. [Set up webhooks in your Customer Area](#set-up-webhooks-in-your-customer-area).
3. [Accept webhook events](#accept-webhooks).

Embedded video (Vimeo): <https://player.vimeo.com/video/843200416>

## 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.\
  **Note:** If you plan to implement OAuth 2.0 for your webhook server, configure this endpoint to accept messages with an access token that has the correct permission scope.

* 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.

* Authentication

  * If you plan to use basic authentication, you need the following for the webhook server:

    * username
    * password

  * If you plan to set up OAuth 2.0 for the **Standard webhook** type, you need the following:

    * Client ID
    * Client secret
    * URL
    * Scope (optional)

  You need to enter these in your Customer Area in [Step 2](#set-up-webhooks-in-your-customer-area).

Depending on your network and security requirements, you might also need to [add our network to your firewall's allowlist](/development-resources/webhooks/secure-webhooks#domain-and-ip-addresses).

## 2. Set up webhooks in your Customer Area

In your [Customer Area](https://ca-test.adyen.com/), enable and configure webhooks for your [company account](/account/account-structure/#company-account), [merchant account](/account/account-structure/#merchant-accounts), and [merchant account groups](/account/account-structure/#account-groups). However, we [recommend to configure webhooks for your company account](/development-resources/webhooks/configure-and-manage). To set up a webhook for a specific merchant account, create a webhook for your company account, and [configure merchant accounts](/development-resources/webhooks/configure-and-manage) for that webhook.

* You can configure [Payments webhooks](/development-resources/webhooks/webhook-types#payments-webhooks) on the company, merchant account, and merchant account groups.
* You can configure [Platforms webhooks](/development-resources/webhooks/webhook-types#platforms-webhooks) on the company account level only.

**To configure a webhook:**

1. In your [Customer Area](https://ca-test.adyen.com/), 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
   | ------------------------ |   |
   | **OAuth 2.0**            | **Note:** OAuth 2.0 support is available for the **Standard webhook** type only. If you want to use OAuth 2.0 for access to your webhook endpoint, enter the following for your Identity Provider's OAuth 2.0 server:- **Client ID**
   - **Client secret**
   - **URL**: The location of your Identity Provider's OAuth 2.0 authorization server, where Adyen should request new access tokens. The time-to-live (TTL) setting of your access tokens must be 3599 seconds, at a minimum.
   - **Scope**: The **Scope** is optional. The permission level Adyen's webhook service needs to access to your webhook endpoint. |
   | **Basic authentication** | Enter the following for your webhook server:- **username**
   - **password**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | **HMAC Key**             | Generate a new HMAC Key or use an existing HMAC key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

7. Under **Events** settings, select the [event types](/development-resources/webhooks/webhook-types/#event-codes) for this webhook. Some webhook types do not support more than one event type, 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 type, so this section does not appear.

9. Select **Save configuration**.

## 3. Accept webhooks

We require you to acknowledge every webhook event with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), for example **200** or **202**. If we do not receive this response within 10 seconds for an reason, such as your server is down or your service is unavailable, all webhook events to your endpoint go to the [retry queue](/development-resources/webhooks/troubleshoot#retry-queue).

In addition to accepting the webhook, there are other steps you should take to [handle your webhooks](/development-resources/webhooks/handle-webhook-events).

For information about the structure and content of webhooks, refer to [Webhook structure and types](/development-resources/webhooks/webhook-types).

## 4. Test and go live

Embedded video (Vimeo): <https://player.vimeo.com/video/843200465>

### Test your webhooks server

Your server must [acknowledge webhooks with a successful HTTP response status code (like **202**)](#accept-webhooks).

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
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 types that you can test for this webhook.
4. Select the edit **icon
5. Select **Test configuration**.
6. If you are on a [company account](/account/account-structure#company-account), select a **Merchant account** from the dropdown list.
7. In the **Event** dropdown list, select the [event type](/development-resources/webhooks/webhook-types#event-codes) to test webhooks for.

If the test webhook failed, you get an error message with the reason. [Troubleshoot the problem](/development-resources/webhooks/troubleshoot).

### End-to-end testing

We recommend you create a test payment and test the webhooks associated with it. Match the test payment to the webhook you receive with the `pspReference` or `merchantReference` within the [webhook message](/development-resources/webhooks/webhook-types#webhook-structure).

### Go live

1. Follow the instructions in [Set up webhooks in your Customer Area](#set-up-webhooks-in-your-customer-area) from the [live Customer Area](https://ca-live.adyen.com/) to create webhook subscriptions on the live environment.\
   **Note:** Adyen does not provide a "copy" function for moving your webhook configurations from the test environment to the live environment. You need to configure all of your webhook subscriptions in the live environment.
2. Test webhooks in your [live Customer Area](https://ca-live.adyen.com/).
3. If you are verifying HMAC signatures, make sure that you use the HMAC key from your [live Customer Area](https://ca-live.adyen.com/), which is different from the HMAC key from your [test Customer Area](https://ca-test.adyen.com/).

## Configure webhooks for multiple merchant accounts

If you are on your company account, you can configure webhook settings for all merchant accounts, or for a group of merchant accounts you decide to include/exclude.

1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Webhooks**.

2. From the list of webhooks, select the one to configure.

3. Select either **Edit webhook** or the edit icon **.

4. Under **General**, select one of the following options from the **Merchant Accounts** dropdown menu:

   * **All merchant accounts** to apply the webhook settings to all merchant accounts.
   * **Include only specific merchant accounts** and select the merchant accounts to include.
   * **Exclude specific merchant accounts** and select the merchant accounts to exclude.

5. Select **Save configuration**.

## Configure your existing webhook endpoint

You can change the endpoint of your existing webhook.

Adyen requires you to use HTTPS endpoints with a [compatible TLS configuration](/development-resources/integration-security-guide/#use-the-correct-tls-configuration) to receive Adyen webhook events. Before you configure your endpoint to receive Adyen webhook events, you need to make sure it supports connections using the correct TLS version and cipher suite.

### Update your endpoint URL

1. Log in to your [Customer Area](https://ca-test.adyen.com/).\
   If you are updating an endpoint for a platforms webhook, make sure you have your company account selected.

2. Go to **Developers** > **Webhooks**.

3. From the list of webhooks, select the one to configure.

4. Select **Edit webhook** or the edit icon **.

5. Under **Server configuration**, configure the following:

   | Setting                 | Description                                                           |
   | ----------------------- | --------------------------------------------------------------------- |
   | **URL**                 | Your webhook server's HTTPS URL. The URL must be publicly accessible. |
   | **Method**              | JSON, HTTP POST, or SOAP                                              |
   | **Encryption protocol** | TLSv1.2 or TLSv1.3                                                    |

6. Select **Save configuration**.

#### If you want to change your endpoint and disable the old endpoint for receiving webhooks:

1. [Add a new endpoint in your Customer Area](#set-up-webhooks-in-your-customer-area).
2. [Disable the old endpoint](#disabling-webhooks).

## Disable and delete webhook configurations

You may want to disable webhooks when:

* Your webhook endpoint is temporarily unable to receive webhooks, for example during server maintenance.
* You have set up a new webhook endpoint for webhooks.

To disable a webhook configuration:

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Select the account for which you want disable your webhook configuration.
3. Go to **Developers** > **Webhooks**.
4. From the list of webhook configurations, select the webhook you want to disable.
5. Under **General**, clear the **Enabled** toggle to disable the webhook.
6. Select **Save configuration**.

In the list of webhook configurations, you will see the status **Disabled** next to the webhook.

We will then queue all webhook events to this endpoint. You will receive the queued webhook events when you reactivate this endpoint configuration by selecting the **Active** checkbox.

Webhook configurations that have been inactive for more than six months are automatically deleted.

To delete a webhook configuration:

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Select the account for which you want to delete your webhook configuration.
3. Go to **Developers** > **Webhooks**.
4. Next to the webhook configuration you want to delete, select the delete icon **.
5. Select **Delete** to confirm your choice to delete the webhook configuration.
