{"title":"Signing notifications with HMAC","category":"Classic Platforms","creationDate":1680003120,"content":"
\n

This feature is supported from Notifications v5<\/a> and later.<\/p>\n

For information about platform integrations built after August 1, 2022, refer to our new integration guide<\/a> instead.<\/p>\n<\/div><\/div>\n

By default, Adyen notifications use basic authentication. You can optionally enable\u00a0Hash-based Message Authentication Code (HMAC)<\/a>\u00a0signatures, which adds an extra layer of security to your standard notifications<\/a>.\u00a0<\/p>\n

An HMAC signature is calculated using a request's key-value pairs and a secret key, which is known only to you and the Adyen payments platform. By verifying this signature, you'll confirm that the notification was not modified during transmission.<\/p>\n

Enable HMAC signatures<\/h2>\n

You can use any\u00a032bit hexadecimal<\/strong>\u00a0HMAC key you like. If you subscribe to payment notifications you can reuse the same key. For more information, see\u00a0Signing notifications with HMAC<\/a>.<\/p>\n

\n

If you generate a new HMAC key, your previous notifications will still be signed with your previous HMAC key.<\/p>\n<\/div><\/div>\n

Subscribe to notifications<\/h2>\n

Subscribe to notifications with a HMAC Signature Key to receive HMAC signed notifications to\u00a0the URL you specify in the\u00a0\/createNotificationConfiguration<\/code>\u00a0call. We activate the ACCOUNT_HOLDER_VERIFICATION<\/a> notification and send it to the endpoint on your server (https:\/\/www.merchant-domain.com\/notification-handler)\u00a0using the specified connection credentials (testUserName<\/strong><\/span>\u00a0and\u00a0testPassword<\/strong><\/span>).<\/p>\n

\n <\/code-sample>\n<\/div>\n
\n <\/code-sample>\n<\/div>\n

Verify HMAC signature<\/h2>\n

To verify the signature, retrieve the\u00a0values of the\u00a0HmacSignature<\/code>\u00a0and\u00a0Protocol<\/code> parameters from the HTTP header of the incoming notification.<\/em>\u00a0HmacSignature<\/code> contains the signature itself and\u00a0Protocol<\/code> is the protocol used to create the signature (only SHA256 is supported).<\/p>\n

To compute the HMAC signature, apply the algorithm\/protocol to the whole HTTP body using the key. If the computed HMAC signature is equal to the one in the header, the verification is successful.<\/p>\n

\n

Perform this check before deserializing\u00a0the request. If you perform deserialization before verifying, a valid signature may fail due to a different order of the JSON elements\u00a0<\/p>\n<\/div><\/div>\n

HMAC signature examples<\/h2>\n

To calculate the HMAC signature:<\/p>\n

import org.junit.jupiter.api.Assertions;\nimport org.junit.jupiter.api.Test;\n\nimport javax.crypto.Mac;\nimport javax.crypto.SecretKey;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.math.BigInteger;\nimport java.nio.charset.StandardCharsets;\nimport java.security.InvalidKeyException;\nimport java.security.NoSuchAlgorithmException;\nimport java.util.Base64;\n\npublic class MarketplaceNotificationHmacExampleTest {\n\n    @Test\n    public void testMarketplaceNotificationHmac() {\n\n        \/\/ Example HEX Key (submitted at the moment of subscription)\n        String hmacSignatureKey = \"79A3EAF309C43708726A8C284C0D72618696A12E840DFA1DF3A158AFA3B577DA\";\n\n        \/\/ Signature. Retrieved from HTTP header under the name HmacSignature.\n        String hmacSignature = \"A2bHr0WPlKg1fJLVEDReVAdUDWt3znmsuYvp2KdihXY=\";\n\n        \/\/ Protocol. Retrieved from HTTP header under the name Protocol.\n        String protocol = \"HmacSHA256\";\n\n        \/\/ Payload. the payload of the notification consists on the whole body of the notification\n        String payload = \"{\\\"eventDate\\\":\\\"2018-07-09T12:07:27+02:00\\\",\\\"eventType\\\":\\\"ACCOUNT_HOLDER_CREATED\\\",\\\"executingUserKey\\\":\\\"ws\\\",\\\"live\\\":false,\\\"pspReference\\\":\\\"9915311308462016\\\",\"\n                + \"\\\"content\\\":{\\\"invalidFields\\\":[],\\\"pspReference\\\":\\\"9915311308462016\\\",\\\"accountCode\\\":\\\"9915311308462024\\\",\\\"accountHolderCode\\\":\\\"6750d8cf-80ab-4a34-b2c5-f8a1f37a79da\\\",\"\n                + \"\\\"accountHolderDetails\\\":{\\\"bankAccountDetails\\\":[],\\\"email\\\":\\\"testEmail@gmail.com\\\",\\\"individualDetails\\\":{\\\"name\\\":{\\\"firstName\\\":\\\"TestFirstName\\\",\\\"gender\\\":\\\"MALE\\\",\"\n                + \"\\\"lastName\\\":\\\"TestData\\\"}},\\\"merchantCategoryCode\\\":\\\"7999\\\"},\\\"accountHolderStatus\\\":{\\\"status\\\":\\\"Active\\\",\\\"processingState\\\":{\\\"disabled\\\":false,\"\n                + \"\\\"processedFrom\\\":{\\\"currency\\\":\\\"EUR\\\",\\\"value\\\":0},\\\"processedTo\\\":{\\\"currency\\\":\\\"EUR\\\",\\\"value\\\":0},\\\"tierNumber\\\":0},\\\"payoutState\\\":{\\\"allowPayout\\\":false,\"\n                + \"\\\"disabled\\\":false,\\\"tierNumber\\\":0},\\\"events\\\":[]},\\\"legalEntity\\\":\\\"Individual\\\",\\\"verification\\\":{}}}\";\n\n        try {\n\n            \/\/ decode HEX Key into bytes\n            byte[] keyBytes = new BigInteger(hmacSignatureKey, 16).toByteArray();\n\n            \/\/ get payload in bytes\n            byte[] payloadBytes = payload.getBytes(StandardCharsets.UTF_8);\n\n            \/\/ instantiate the MAC object using HMAC \/ SHA256\n            Mac hmacSha256 = Mac.getInstance(protocol);\n\n            \/\/ create a key object using the secret key and MAC object\n            SecretKey secretKey = new SecretKeySpec(keyBytes, hmacSha256.getAlgorithm());\n\n            \/\/ initialise the MAC object\n            hmacSha256.init(secretKey);\n\n            \/\/ finalise the MAC operation\n            byte[] signedPayload = hmacSha256.doFinal(payloadBytes);\n\n            \/\/ encode the signed payload in Base64\n            byte[] encodedSignedPayload = Base64.getEncoder().encode(signedPayload);\n            System.out.println(\"original HMAC signature: \" + hmacSignature);\n            System.out.println(\"computed HMAC signature: \" + new String(encodedSignedPayload, StandardCharsets.US_ASCII));\n\n            \/\/ assert the calculated Base64 encoded HMAC is equal to the received Base64 encoded HMAC\n            Assertions.assertArrayEquals(encodedSignedPayload, hmacSignature.getBytes(StandardCharsets.UTF_8));\n\n        } catch (NoSuchAlgorithmException e) {\n            \/\/ HmacSHA256 should be supported\n        } catch (InvalidKeyException e) {\n            \/\/ The key is invalid\n        }\n    }\n}<\/code><\/pre>\n
If the calculated\u00a0HmacSignature<\/code>\u00a0matches the value you received in the notification, the notification wasn't modified during transmission.<\/p>\n
The following is an example of a header containing an HMAC signature:<\/p>\n
[Content-Type: application\/json; charset=utf-8, Authorization: Basic dGVzdFVzZXJOYW1lOnRlc3RQYXNzd29yZA==, HmacSignature: awA4ZTCAYLp\/ctyt9yFPlidqZcLjWs5EZikhIQCz98k=, Protocol: HmacSHA256, Content-Length: 819, Host: localhost:57851, Connection: Keep-Alive, User-Agent: Adyen HttpClient 1.0, Accept-Encoding: gzip,deflate]<\/code><\/pre>\n
See also<\/h2>\n