Ctrlk
Sign up for free
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks upgrade to the SHA algorithm

If you are using shopping cart integration, make sure to follow the instructions from the Shopping cart integration upgrade to the SHA algorithm documentation first.

1

Access the Webhooks settings

  1. Log in to your 2Checkout account.

  2. Navigate to Dashboard > Integrations > Webhooks and API.

Webhooks and API screen

  1. Click the INS Settings / IPN Settings / LCN Settings tab based on the webhook type you are updating. Depending on your needs, there are several options for making the switch.

Add a new URL with SHA2/3 hash (Recommended)

  • Click on Add endpoint.

  • Add the new INS name and URL, select the hashing algorithm, then click Save endpoint.

  • After setting up the URL for the new endpoint, navigate to the trigger list associated with the endpoint and click Edit.

edit trigger

  • On the next page, scroll to the Parameters section, deselect the md5_hash parameter, select the hash parameter, and click Save trigger.

edit parameter

  • The new INS endpoint and its hashing algorithm will appear in the URL list. When ready, remove the old endpoint with MD5 and use only the SHA endpoint.

  • Optionally, for enhanced security, you can validate the hash received in INS. See: https://verifone.cloud/docs/2checkout/API-Integration/Webhooks/Instant-Notification-Service-%2528INS%2529/INS-read-receipt-response

new endpoint

  • Click Add IPN URL.

IPN settings

  • Add the IPN URL and select the hash algorithm.

  • The new IPN URL and its hashing algorithm will appear in the URL list. When ready, remove the old endpoint with MD5 and use only the SHA endpoint.

IPN settings sha

This option is suitable for merchants already using the LCN in production and processing orders through the platform.

  • Click Add LCN URL.

LCN settings

  • Add the LCN URL and select the hash algorithm.

  • The new LCN URL and its hashing algorithm will appear in the URL list. When ready, remove the old endpoint with MD5 and use only the SHA endpoint.

LCN settings sha

Keep both the SHA2/SHA3 and MD5 hash

You will receive notifications with multiple hash parameters. Adjust your integration to correctly process the extra hash parameter and respond with the new algorithm. See this article for IPN code samples.

  • Click Edit for the existing URL corresponding to your default IPN listener.

Edit IPN hash

  • Select the additional hash algorithm and click Save.

IPN save new hash

  • The changes will be shown in the URL list.

IPN new hash URL

  • After you successfully validate notifications using SHA2/SHA3, remove the MD5 hash from your endpoint.

This approach may be suitable for merchants using LCNs, allowing a smooth transition: both hashes will be sent in LCN until August 15th, 2024.

Prerequisite: Adjust your integration to process multiple hash parameters. See LCN code samples: https://verifone.cloud/docs/2checkout/API-Integration/Webhooks/08License_Change_Notification_%2528LCN%2529/LCN-code-sample

  • Click Edit for the URL corresponding to your default LCN listener.

LCN edit URL hash

  • Select the additional hash algorithm and click Save.

LCN select URL hash

  • The changes will be shown in the URL list.

LCN new URL hash

  • After you successfully validate notifications using SHA2/SHA3, remove the MD5 hash from your endpoint.

Replace the MD5 hash with SHA2/SHA3

This approach is best if you are using a sandbox environment or can accept service interruption because MD5 will no longer be sent to the endpoint until you update your integration to support SHA2/SHA3. Check this link for more details.

  • INS switch to SHA2/3: https://verifone.cloud/docs/2checkout/API-Integration/01Start-using-the-2Checkout-API/2Checkout-API-general-information/Migration_guide_SHA2_SHA3/Webhooks_upgrade_to_the_SHA_algorithm#-tab-0-name

  • IPN switch to SHA2/3: https://verifone.cloud/docs/2checkout/API-Integration/01Start-using-the-2Checkout-API/2Checkout-API-general-information/Migration_guide_SHA2_SHA3/Webhooks_upgrade_to_the_SHA_algorithm#-tab-1-name

  • LCN switch to SHA2/3: https://verifone.cloud/docs/2checkout/API-Integration/01Start-using-the-2Checkout-API/2Checkout-API-general-information/Migration_guide_SHA2_SHA3/Webhooks_upgrade_to_the_SHA_algorithm#-tab-2-name

  • Click Edit for the existing endpoint corresponding to your default INS listener.

edit endpoint

  • Selecting any of the SHA algorithms will automatically deselect MD5. Click Save endpoint.

INS settings sha 1

  • The changes will be shown in the endpoint list.

new hash

  • After setting up the URL, navigate to the trigger list, click Edit for the trigger, deselect md5_hash, select the hash parameter, and click Save trigger.

edit trigger 1 edit parameter sha

  • Optionally, validate the hash received in INS (link placeholder in original).

  • Click Edit for the existing URL corresponding to your default IPN listener.

IPN settings sha 3

  • Select the SHA algorithm and deselect MD5. Click Save.

  • The changes will be shown in the URL list.

IPN settings sha 2

  • Click Edit for the existing URL corresponding to your default LCN listener.

LCN settings sha 1

  • Select the SHA algorithm and deselect MD5. Click Save.

LCN settings sha 1

  • The changes will be shown in the URL list.

LCN settings sha 3

Troubleshooting

Even after upgrading your INS/IPN/LCN webhooks from MD5 to SHA2/SHA3, verify operations using the reports and retry features.

1

Find failed webhooks

  1. Log in to your 2Checkout account.

  2. Navigate to Dashboard > Reports center > API & Webhooks.

API & Webhooks

  1. Select Webhooks as Event source, choose IPN, LCN, or INS as Webhooks, and Fail as Status. Optionally filter by Order/License reference. Press Search.

report settings

  • Failed entries will be listed. Click the Action icon for details.

Action
2

Inspect retry details

  • The retry mechanism applies only to failed INS/IPN/LCN. Request/response details for each webhook are available in the report.

INS troubleshooting 1 INS troubleshooting 2

  • The report shows request/response details for each retry.

info box INS troubleshooting 3

3

Resend INS

  • Select the failed webhook and click Resend.

resend ins 1

  • Click Proceed to resend the INS webhook.

resend ins 2
4

Resend IPN

  1. Click the order number from the Order reference list.

order reference list

  1. Select Resend notification(s).

Resend notification(s) IPN

  1. Mark Debug IPN? and click Re-send.

Debug IPN

  • Use the debugger to see why the IPN failed and which hash signature was used.

IPN debugger
5

Resend LCN

  1. Click the license number from the License reference list.

License reference list

  1. Select Resend notification(s).

Resend notification(s) LCN

  1. Mark Debug LCN? and click Re-send.

Debug LCN?

  • Use the debugger to see why the LCN failed and which hash signature was used.

LCN debugger

Related:

PreviousAPI Authentication upgrade to the SHA algorithm
NextShopping cart integration upgrade to the SHA algorithm

Last updated

Was this helpful?