Verify HMAC signatures

To protect your server from unauthorised webhook events, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. After you enable HMAC signatures, each webhook event will include a signature calculated using a secret HMAC key and a payload from the webhook. By verifying this signature, you confirm that the webhook was sent by Adyen, and was not modified during transmission.

To verify HMAC signatures, you can either:

• Use one of our libraries.
• Build your own custom solution.

Enable HMAC signatures

To enable HMAC signed webhook events, generate a secret HMAC key in your Customer Area. The secret HMAC key is linked to a standard webhook endpoint. If you have multiple endpoints for receiving webhooks, you need to generate an HMAC key for each of them.

To start receiving HMAC signed webhooks:

1. Log in to your Customer Area. If you have set up webhooks for your merchant accounts, switch to the merchant account.
2. Go to Developers > Webhooks.
3. Select the edit icon for the Standard webhook you want to enable HMAC for.
4. Under Security, select the edit icon for HMAC key.
5. Select Generate.
6. Copy the HMAC key using the copy icon . Store it securely in your system - you won't be able to restore it later.
7. Select Apply, then Save changes.

The HMAC key will now be used to sign webhook events that we send to your server. The signature is
included in the additionalData field:

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "hmacSignature":"+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw="
            },
          ...
         }
      }
   ]
}

Verify using our libraries

You can verify signatures using our:

• Java library
• PHP library
• C# library
• JavaScript library

// YOUR_HMAC_KEY from the Customer Area
String hmacKey = "YOUR_HMAC_KEY";
// Notification Request JSON
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
HMACValidator hmacValidator = new HMACValidator();
NotificationHandler notificationHandler = new NotificationHandler();
NotificationRequest notificationRequest = notificationHandler.handleNotificationJson(notificationRequestJson);
// Handle multiple notificationRequests
List<NotificationRequestItem> notificationRequestItems = notificationRequest.getNotificationItems();
for ( NotificationRequestItem notificationRequestItem : notificationRequestItems ) {
    // Handle the notification
    if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
        // Process the notification based on the eventCode
        String eventCode = notificationRequestItem.getEventCode();
    } else {
        // Non valid NotificationRequest
        System.out.print("Non valid NotificationRequest");
    }
}

// YOUR_HMAC_KEY from the Customer Area
$hmacKey = "YOUR_HMAC_KEY";
// Notification Request JSON
$jsonRequest = "NOTIFICATION_REQUEST_JSON";
$notificationRequest = json_decode($jsonRequest, true);
$hmac = new \Adyen\Util\HmacSignature();
// Handling multiple notificationRequests
foreach ( $notificationRequest["notificationItems"] as $notificationRequestItem ) {
  $params = $notificationRequestItem["NotificationRequestItem"];
  // Handle the notification
  if ( $hmac->isValidNotificationHMAC($hmacKey, $params) ) {
    // Process the notification based on the eventCode
    $eventcode = $params['eventCode'];
    print_r($eventcode);
  } else {
    // Non valid NotificationRequest
  }
}

// YOUR_HMAC_KEY from the Customer Area
string hmacKey = "YOUR_HMAC_KEY";
// Notification Request JSON
string notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
var hmacValidator = new HmacValidator();
var notificationHandler = new NotificationHandler();
var handleNotificationRequest = notificationHandler.HandleNotificationRequest(notificationRequestJson);
// Handle multiple notificationRequests
List<NotificationRequestItemContainer> notificationRequestItemContainers = handleNotificationRequest.NotificationItemContainers;
foreach ( var notificationRequestItemContainer in notificationRequestItemContainers ) {
    var notificationItem = notificationRequestItemContainer.NotificationItem;
    // Handle the notification
    if ( hmacValidator.IsValidHmac(notificationItem, hmacKey) ) {
         // Process the notification based on the eventCode
        string eventCode = notificationItem.EventCode;
    } else {
        // Non valid NotificationRequest
    }
}

const { hmacValidator } = require('@adyen/api-library');
// YOUR_HMAC_KEY from the Customer Area
const hmacKey = "YOUR_HMAC_KEY";
const validator = new hmacValidator()
// Notification Request JSON
const notificationRequest = NOTIFICATION_REQUEST_JSON;
const notificationRequestItems = notificationRequest.notificationItems
// Handling multiple notificationRequests
notificationRequestItems.forEach(function(notificationRequestItem) {
    // Handle the notification
    if( validator.validateHMAC(notificationRequestItem, hmacKey) ) {
        // Process the notification based on the eventCode
        const eventCode = notificationRequestItem.eventCode;

    } else {
        // Non valid NotificationRequest
        console.log("Non valid NotificationRequest");
    }
});

Verify using your own solution

To build your own solution for verifying HMAC signatures, follow these steps:

Step 1: Construct the payload

Concatenate the following values from the webhook event, in the given order:

Assign an empty string to any fields that are empty, and use a colon (":") to delimit the values.

For the above values, with an empty originalReference, you get:

7914073381342284::TestMerchant:TestPayment-1407325143704:1130:EUR:AUTHORISATION:true

Step 2: Calculate the HMAC signature

1. Calculate an HMAC using:

   • The SHA256 function.
   • Binary representation of the payload that you constructed in Step 1, given the UTF-8 charset.
   • Binary representation of the HMAC key, given the UTF-8 charset.

2. To get the final signature, Base64-encode the result.

Step 3: Compare signatures

If the signature that you calculated in Step 2 matches the hmacSignature that you received, you'll know that the webhook event was sent by Adyen and was not modified during transmission.

Example

Sample HMAC key:

44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056

Sample webhook event signed using the above HMAC key:

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "hmacSignature":"coqCmt/IZ4E3CzPvMY8zTjQVL5hYJUiBRg8UU+iCWo0="
            },
            "amount":{
               "value":1130,
               "currency":"EUR"
            },
            "pspReference":"7914073381342284",
            "eventCode":"AUTHORISATION",
            "eventDate":"2019-05-06T17:15:34.121+02:00",
            "merchantAccountCode":"TestMerchant",
            "operations":[
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "merchantReference":"TestPayment-1407325143704",
            "paymentMethod":"visa",
            "success":"true"
         }
      }
   ]
}

See also