Webhooks upgrade to the SHA algorithm
Last updated: 05-Apr-2024
If you are using shopping cart integration (e.g.: Shopify, WooCommerce, etc.), make sure to follow the instructions from the Shopping cart integration upgrade to the SHA algorithm documentation first.
- Log into your 2Checkout account.
- Navigate to Dashboard > Integrations > Webhooks and API.
- Click on the IPN Settings / LCN Settings tab.
There are several options for making the switch, depending on your needs. We will detail three ways, each suitable for different situations.
A. Add a new URL with SHA2/3 hash Recommended
- Click on Add IPN URL.
- Add the IPN URL and select the hash algorithm.
- The new IPN URL with its hashing algorithm will be displayed in the URL list. When you’re ready, remove the old endpoint with MD5 and use only the one with SHA algorithm.
Like option A, the third option is suitable for merchants that are already using the LCN in a production environment and process orders through the platform.
- Click on Add LCN URL.
- Add the LCN URL and select the hash algorithm.
- The new LCN URL with its hashing algorithm will be displayed in the URL list. When you’re ready, remove the old endpoint with MD5 and use only the one with SHA algorithm.
B. Add the SHA2/SHA3 hash and keep the MD5 hash
Prerequisite:
This approach means that you will receive an IPN with multiple hash parameters. Therefore, you will first need to adjust your integration to be able to correctly process the extra hash parameter and respond with the new algorithm. Check this article for some IPN code samples.
This approach means that you will receive an IPN with multiple hash parameters. Therefore, you will first need to adjust your integration to be able to correctly process the extra hash parameter and respond with the new algorithm. Check this article for some IPN code samples.
- Click on the Edit button to edit an existing URL corresponding to your default IPN listener.
- Select the additional hash algorithm. Click on Save.
- The changes in the hashing algorithm will be displayed in the URL list.
- After you successfully manage to validate the notification using the SHA2/SHA3 hash algorithm, remove the MD5 hash from your endpoint.
This approach might be suitable for merchants that have been selling through the platform and have been using LCNs. This will allow a smooth transition from one hashing algorithm to another, as both will be sent in the LCN until May 15th, 2024.
Prerequisite:
This approach means that you will receive an LCN with multiple hash parameters. Therefore, you will first need to adjust your integration to be able to correctly process the extra hash parameter and respond with the new algorithm. Check this article for some LCN code samples.
This approach means that you will receive an LCN with multiple hash parameters. Therefore, you will first need to adjust your integration to be able to correctly process the extra hash parameter and respond with the new algorithm. Check this article for some LCN code samples.
- Click on the Edit button to edit an existing URL corresponding to your default LCN listener.
- Select the additional hash algorithm. Click on Save.
- The changes in the hashing algorithm will be displayed in the URL list.
- After you successfully manage to validate the notification using the SHA2/SHA3 hash algorithm, remove the MD5 hash from your endpoint.
C. Add the SHA2/SHA3 hash and deselect the MD5 hash
This approach is best if you are using a sandbox environment, or you can afford some service interruption. This is because we will no longer send MD5 hash to this IPN endpoint, and you will need to adapt your integration to support the SHA2/SHA3 algorithm. Check this link for more details.
- Click on the Edit button to edit an existing URL corresponding to your default IPN listener.
- Select the additional hash algorithm and deselect the MD5 hash. Click on Save.
- The changes in the hashing algorithm will be displayed in the URL list.
This approach is best if you are using a sandbox environment, or you can afford some service interruption. This is because we will no longer send MD5 hash to this LCN endpoint, and you will need to adapt your integration to support the SHA2/SHA3 algorithm. Check this link for more details.
- Click on the Edit button to edit an existing URL corresponding to your default LCN listener.
- Select the additional hash algorithm and deselect the MD5 hash. Click on Save.
- The changes in the hashing algorithm will be displayed in the URL list.
Troubleshooting
Even after upgrading your IPN/LCN webhooks from MD5 to the SHA2/SHA3 algorithm you can make sure your daily operations are not impacted, by following these steps:
-
Log into your 2Checkout account.
-
Navigate to Dashboard > Reports center > API & Webhooks.
-
Select Webhooks as Event source, IPN (Instant Payment Notification) or LNC (License Change Notification) as Webhooks and Fail as Status. You can also filter your search by IPN Order reference. Press on Search.
-
The failed IPN(s)/LCN(s) will be displayed. Select the Action icon to see more information.
-
The retry mechanism is only for the failed IPN/LCN. You can see which one failed via the report and request / response details of each webhook.
Additionally, on the order level, you can click on Resend IPN and, on the subscription level, you can click on Resend LCN feature in debug mode, to be able to see how your setup behaves:
Resend IPN
- Click on the order number, from the Order reference list.
- Select Resend notification(s).
- Mark the Debug IPN? checkbox and click on Re-send.
- On the debugger you can see why the IPN failed and what hash signature was used.
Resend LCN
- Click on the license number, from the License reference list.
- Select Resend notification(s).
- Mark the Debug LCN? checkbox and click on Re-send.
- On the debugger you can see why the LCN failed and what hash signature was used.
- Click on the order number, from the Order reference list.
