Configure and manage webhooks

You can configure webhook subscriptions for your company account, merchant account, and merchant 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 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.

Configure a webhook

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.

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.

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

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 Platforms 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
   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 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, 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.

In addition to accepting the webhook, there are other steps you should take to handle your webhooks.

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

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 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, select a Merchant account from the dropdown list.
7. In the Event dropdown list, select the event type 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 Set up webhooks in your Customer Area from the live environment 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.

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

Update your endpoint URL

1. Log in to your Customer Area.
   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.
2. Disable the old endpoint.

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

To delete a webhook configuration:

1. Log in to your Customer Area.
2. Select the account for which you want 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.