Webhook Notifications

Subscribing to Webhook notifications enables you to receive notifications on your system when a transaction for an order is created or updated in the gateway. This allows you to update your shop system accordingly. The Webhook notification contains the response of the Retrieve Transaction operation.

Webhook notifications with integrations to Hosted Checkout

For the Hosted Checkout integrations, if you use Authentication API for 3-D Secure Authentication, you will receive two Webhook notifications, compared to one if you use 3DS1 functionality.

One after the Payer authentication is complete
One after the Authorization/Pay transaction is complete

The Payer Authentication Webhook will include details of the authentication operation only. It will not include information about the outcome of the financial transaction. The Authorization/Pay Webhook will include the outcome of the financial transaction processing.

Configuring Webhook Notifications

You can configure the following parameters for Webhook notifications in Merchant Administration:

Notification URL—You can configure a global notification URL in Merchant Administration to receive notifications for all transaction updates at this URL. If you wish to override the global URL on a per transaction basis, provide the URL in the field order.notificationUrl in your transaction request. With subsequent transactions, notifications are sent to the URL on the transaction (if provided) or the URL last used for the order.

The URL you provide must conform to the IETF Standard for URLs (see http://www.ietf.org/rfc/rfc2396.txt) otherwise the request is rejected.

API Format—Mastercard Payment Gateway sends Webhook notifications in the format (REST or NVP) that you configure in Merchant Administration.

The notification is sent in the version that was used to submit the transaction request.

Ensuring the Integrity of Webhook Notifications

If you rely on the content of Webhook Notification for business critical reasons, you should consider taking the following steps to ensure the integrity of the data received in the notifications.

Provide a secure (https://) URL as the endpoint, and
Check the Notification Secret
The notification secret is a random, 32 characters string generated by the gateway. The secret is displayed in Merchant Administration when configuring Webhook Notifications. For secure (https://) URLs only, the gateway will include the secret in the X-Notification-Secret header with the message.

The gateway performs validation to ensure you only provide a secure (https://) notification URL as the endpoint.

Alternatively, you can perform a Retrieve Transaction operation using the identifiers in the received notification to obtain the changed details.

Accepting Webhook Notifications

The gateway will consider the delivery of the Webhook notification as successful if your system responds with a successful acknowledgement message containing HTTP 200 Status Code within 2 seconds.

The gateway attempts to send notifications in the same sequence in which updates to the transactions occurred unless the notification requires re-delivery. The re-delivery occurs when the initial notification is not delivered successfully or the acknowledgement message is not received successfully. In such cases, gateway attempts to re-deliver notifications up to 20 times within 3 days after the event occurred. This may result in duplicate notifications being sent to your system. You can use the following fields in the Webhook notification to handle re-delivered notifications:

The X-Notification-Id header uniquely identifies the notification. This header will be identical for duplicate transactions.
The X-Notification-Attempt header indicates the number of attempts made to send the notification.

You can reuse the code from your front-end integration to accept Webhook notifications.

Notification URL API Reference [REST][NVP]