Notification webhooks

Adyen sends notifications through webhooks to inform your system about events that occur in the balance platform. These events include when a card user makes a payment with their Adyen-issued card, or when a merchant starts a refund .

When an event occurs, Adyen makes an HTTP POST request to a URL on your server and includes the details of the event in the request body.

You can use notifications to build your implementations. For example, you can use the information to update balances in your own dashboards or to keep track of incoming funds.

On this page, you'll find information about how to:

1. Set up your webhook endpoint.
2. Configure notifications in your Balance Platform Customer Area.
3. (Recommended) Validate HMAC signatures.
4. Accept notifications.

Step 1: Set up a webhook endpoint

Create an endpoint on your server that:

• Can receive a JSON object.
• Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
• Can handle basic authentication.

Step 2: Configure notifications in your Balance Platform Customer Area

When you have an endpoint ready, you can configure the endpoint in your Balance Platform Customer Area:

1. Log in to your Balance Platform Customer Area.
2. Go to Webhooks.
3. Select the Webhook button in the upper right corner.
4. Choose the type of notification you want to subscribe to and select Add.
5. Under General, select the edit icon and configure the following fields:
   • Server configuration: Enter your HTTPS URL.
   • Description: Add a description for your webhook.
6. Under Security, select the edit icon and configure the following fields:
   • Basic authentication: Enter your server's username and password for basic authentication. We include these details in the header of the notification request to authenticate with your server.
   • HMAC Key: To receive HMAC signed notifications, select Generate. Securely save the HMAC key in your system - you won't be able to restore it later.
7. Select Save webhook.

When you are already receiving webhooks, make sure you accept every notification.

Step 3 (Recommended): Validate the HMAC signature

Adyen signs every notification with an HMAC signature in the request header. You can optionally verify the HMAC signature to add an extra layer of security. By verifying this signature, you'll confirm that the notification was sent by Adyen and was not modified during transmission.

1. For every notification that you receive, get the values from the following headers:
   • HmacSignature: Contains the signature.
   • Protocol: The protocol used to create the signature, HmacSHA256.
2. Calculate the signature using:
   • SHA256.
   • The request body and secret key in binary.
     Make sure that the request body is as it is—don't deserialize it.
   Then base64-encode the result.
3. Compare the HmacSignature received from the header and the calculated signature. If the signatures match, then the notification was sent by Adyen and was not modified during transmission. Here are some examples of how you would validate the HMAC signature.

import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Arrays;
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.DecoderException;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.binary.Hex;
import org.junit.Assert;
import org.junit.Test;

public class NotificationHmacExampleTest {

    @Test
    public void testNotificationHmac(){

        Base64 base64 = new Base64();
        // Example HEX Key (submitted at the moment of subscription)
        String hmacSignatureKey = "6D5BADA576A73109D879220DCB793FFD67DEF7AA18C74CCC0AB66FD87AC8AEEA";

        // Signature. Retrieved from HTTP header under the name HmacSignature.
        String hmacSignature = "lFrZb+1R+3Hfnbh+VM4Jt5qZYre5r3Lu5RJeQQSsl6M=";

        // Protocol. Retrieved from HTTP header under the name Protocol.
        String protocol = "HmacSHA256";

        // Payload. the payload of the notification consists on the whole body of the notification
        String payload = "{\"data\":{\"balancePlatform\":\"YourBalancePlatform\",\"creationDate\":\"2022-11-21T16:48:35+01:00\",\"id\":\"3JERI45WZHNCUHZY\",\"accountHolder\":{\"description\":\"Farah's Fedoras Company Account Holder\",\"id\":\"AH3227C223222C5GXTQM35ZX3\"},\"amount\":{\"currency\":\"EUR\",\"value\":900},\"balanceAccount\":{\"description\":\"Farah's Fedoras Balance Account\",\"id\":\"BA32272223222C5GXTQM43WKF\"},\"description\":\"Porcelain Doll: Eliza (20cm)\",\"originalAmount\":{\"currency\":\"EUR\",\"value\":900},\"platformPayment\":{\"account\":\"BA32272223222C5GXTQM43WKF\",\"modificationMerchantReference\":\"<auto>\",\"modificationPspReference\":\"G8X8VXGN2MQ7C782\",\"paymentMerchantReference\":\"uniqueReference\",\"paymentPspReference\":\"H42JQZ4RTGXXGN82\",\"reference\":\"6124145\",\"type\":\"BalanceAccount\"},\"reference\":\"6124145\",\"status\":\"Authorised\"},\"environment\":\"test\",\"type\":\"balancePlatform.payment.created\"}";

        try {

            // decode HEX Key into bytes
            byte[] keyBytes = Hex.decodeHex(hmacSignatureKey.toCharArray());

            // get payload in bytes
            byte[] payloadBytes = payload.getBytes("UTF-8");

            // instantiate the MAC object using HMAC / SHA256
            Mac hmacSha256 = Mac.getInstance(protocol);

            // create a key object using the secret key and MAC object
            SecretKey secretKey = new SecretKeySpec(keyBytes, hmacSha256.getAlgorithm());

            // initialise the MAC object
            hmacSha256.init(secretKey);

            // finalize the MAC operation
            byte[] signedPayload = hmacSha256.doFinal(payloadBytes);
            // encode the signed payload in Base64
            byte[] encodedSignedPayload = base64.encode(signedPayload);
            System.out.println("original HMAC signature: " + hmacSignature);
            System.out.println("computed HMAC signature: " + new String(encodedSignedPayload, "ASCII"));

            // assert the calculated Base64 encoded HMAC is equal to the received Base64 encoded HMAC
            Assert.assertTrue(Arrays.equals(encodedSignedPayload, hmacSignature.getBytes("UTF-8")));

        } catch (NoSuchAlgorithmException e) {
            // HmacSHA256 should be supported
        } catch (UnsupportedEncodingException e) {
            // UTF-8 should be supported
        } catch (DecoderException e) {
            // Check key for odd number or characters outside of HEX (base16)
        } catch (InvalidKeyException e) {
            // The key is invalid
        }
    }
}

import hmac
import hashlib
import base64

def checkHmac(payload, hmac_key, hmac_sig):
  # payload is the request body as it is
  # hmac_key is the secret
  # hmac_sig is the signature from the header
  hmac_key = binascii.a2b_hex(hmac_key)
  # Calculate signature
  calculatedHmac = hmac.new(hmac_key, payload.encode('utf-8'), hashlib.sha256).digest()
  calculatedHmac_b64 = base64.b64encode(calculatedHmac)

  receivedHmac_b64 = hmac_sig.encode('utf-8')
  validSignature = hmac.compare_digest(receivedHmac_b64, calculatedHmac_b64)

  if not validHMAC:
      print('HMAC is invalid: {} {}'.format(receivedHmac_b64, calculatedHmac_b64))
      return False

  return True

Step 4: Accept notifications

To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with a response containing the string: [accepted].

When your server receives a notification:

1. Verify the HMAC signature included in the notification.
   This is to confirm that the notification 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 notification.
2. Store the notification in your database.
3. Acknowledge the notification with HTTP 200 and [accepted] in the response body.
4. Apply your business logic.
   Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important messages from reaching your system.

Adding our network to your firewall's allowlist

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

We do not provide a list of IP addresses. IP addresses change over time due to various reasons, for example, ISP configuration changes. This can lead to disruptions in receiving notification webhooks if IP addresses are hard-coded.

To make sure you can communicate with our network, you can either:

• Use a domain allowlist. Include our domain out.adyen.com if your network configuration allows domain allowlisting.
• Systematically resolve our IP addresses. Perform DNS lookup for out.adyen.com. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.