To protect your server from unauthorised notifications, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. By verifying the signature included in a notification, you'll confirm that the notification was sent by Adyen, and was not modified during transmission. For more information, refer to Verify HMAC signatures.
We also recommend that you use basic authentication over HTTPS. After you have set up a username and password for basic authentication in your Customer Area, we will include these in the header of the notification, so you can authenticate the request with your server. For this to be secure, you need to use HTTPS for your notifications endpoint, otherwise your basic authentication credentials can be compromised.
Basic authentication only guarantees that the notification was sent by Adyen, not that it wasn't modified during transmission.
Changing your HMAC key
If you generate a new HMAC key, it might take some time to propagate this in our infrastructure, so make sure that you can still accept notifications signed with your previous HMAC key for some time.
Changing your notifications endpoint
If you need to change your endpoint for receiving notifications:
You might want to disable notifications when:
- Your endpoint is temporarily unable to receive notifications, for example during server maintenance.
- You have set up a new endpoint for notifications.
To disable notifications:
- Log in to your Customer AreaCustomer Area.
- Go to Account > Server communication.
- Next to the endpoint that you wish to disable, click Edit & Test.
- Clear the Active checkbox.
- Click Save Configuration.
We will then queue all notifications to this endpoint. You will receive the queued notifications when you reactivate this endpoint by checking the Active checkbox.
If you change the URL while the notifications are disabled, you will not receive the queued notifications, as these will be sent to the old URL.
In some cases you might receive the same AUTHORISATION notification twice, so make sure that your system is able to deal with duplicates. These duplicate notifications have the same values in the
pspReference fields, while the
eventDate and other fields may differ. Your server should use the details contained in the latest notification.
To ensure that notifications are properly delivered, your server should acknowledge them with an appropriate response message.
If we don't receive the response message within 10 seconds, all notifications to this endpoint will be queued. We'll then retry sending the notification until it is accepted. Once accepted, you'll also receive all the queued notifications.
Retry attempts happen regularly for up to 7 days, at increasing time intervals:
- 2 minutes
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour
- 2 hours
- 4 hours
After that, retries happen every 8 hours for the following 7 days.
If your server is not acknowledging notifications, we will inform you of this with a system message. For more information, see How do I subscribe to system messages.
The notification queues are maintained separately for each endpoint. If you have multiple endpoints for receiving notifications and we have queued notifications for one of them, this won't affect the remaining endpoints.
If your endpoint is not accepting notifications properly, you can troubleshoot the issue yourself:
- Log in to your Customer Area
- Go to Account > Server Communications.
- Next to the notification endpoint that is not working properly, click Troubleshoot.
You will see the request for which the expected
[accepted]response is not returned by your server.