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.notificationUrlin 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. - API Format—Mastercard Gateway sends Webhook notifications in the format (REST or NVP) that you configure in Merchant Administration.
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.
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.