Callback Issues with LiteSpeed

Troubleshooting Callback Issues with LiteSpeed and HMAC Verification

Overview

Some merchants using LiteSpeed web servers have reported that they are not receiving payment callback requests from Paymento, even though the transactions are processed successfully on-chain. This issue is typically caused by LiteSpeed blocking or modifying HTTP headers, which interferes with Paymento's HMAC signature verification.

Root Cause

Paymento signs each callback using an HMAC-SHA256 signature, included in the X-Paymento-HMAC HTTP header. This ensures that the callback is:

  • Authenticated

  • Untampered

  • From a trusted source (Paymento)

However, LiteSpeed server configurations may block or strip custom HTTP headers by default, especially those starting with X-. As a result, your server never receives the X-Paymento-HMAC header, and your backend cannot verify the request.

Symptoms

  • Payment is confirmed on the blockchain

  • Transaction is visible in the Paymento dashboard

  • Your WHMCS or platform shows the invoice as unpaid or pending

  • No logs or failed attempts are seen in your server

How to Fix It

✅ Step 1: Check if the X-Paymento-HMAC header is reaching your app

Use a request logger or write a simple endpoint to dump all incoming headers and see if X-Paymento-HMAC is present.

✅ Step 2: Whitelist or allow custom headers in LiteSpeed

You may need to modify your .htaccess file or LiteSpeed Web Admin settings to allow custom headers.

Add this to your .htaccess:

RewriteEngine On
RewriteCond %{HTTP:X-Paymento-HMAC} ^(.+)$
RewriteRule .* - [E=HTTP_X_PAYMENTO_HMAC:%1]

Or ensure your LiteSpeed is not blocking headers by default in:

  • LiteSpeed WebAdmin Console → Configuration → Server → Security

Also, make sure you’re not behind a firewall or WAF (e.g., ModSecurity) that strips unknown headers.

✅ Step 3: Test Again

After making these changes, reinitiate a test payment. The X-Paymento-HMAC header should now be passed through to your application, and the transaction should update correctly.

Summary

If you're using LiteSpeed and experiencing callback issues, there's a high chance the X-Paymento-HMAC header is being blocked. Allowing custom headers or explicitly whitelisting X-Paymento-HMAC resolves the problem and ensures secure callback verification.

For further help, contact our support team and let us know you're using LiteSpeed — we’ll help you validate your setup.

PreviousLedger live XPUB Mismatch

Last updated