Fix webhook signature verification for payloads containing special characters

[sagar-rai]

In certain environments, such as Scala Play 2.8/2.9, Utils.verifyWebhookSignature may return false for valid webhook requests when the payload contains special characters or multi-byte text. The issue appears to come from the SDK accepting only a String, while framework-level parsing can alter the raw request body before verification.

Problem

Utils.verifyWebhookSignature currently accepts only a String.

This issue is especially likely when a user uses a framework such as Play to read the request body into a String before passing it to the SDK, since webhook validation is safest when performed on the raw body bytes rather than a parsed or re-encoded string.

Reproduction

1. Receive a Razorpay webhook containing special characters or multi-byte characters in fields such as customer name or notes.
2. Parse the HTTP body as a String in Scala Play.
3. Pass the resulting string to Utils.verifyWebhookSignature(...).
4. Observe that the method returns false even though the webhook is valid.

Proposed Fix

1. Add an overload that accepts raw bytes

Introduce a new method in Utils that accepts byte[] so developers can pass the raw request body directly:

public static boolean verifyWebhookSignature(byte[] payload, String expectedSignature, String webhookSecret) throws RazorpayException {
    // Use raw bytes directly to avoid encoding issues
}

2. Use UTF-8 explicitly in string-based hashing

Update the existing implementation so string payloads are always converted using UTF-8:

// Current
byte[] hash = sha256_HMAC.doFinal(payload.getBytes());

// Proposed
byte[] hash = sha256_HMAC.doFinal(payload.getBytes(UTF-8));
//Similar charset as used for encoding the webhook secret to bytes

This makes the behavior deterministic across environments and avoids platform-dependent failures.

Why This Matters

Razorpay’s webhook validation flow depends on the exact payload used to generate the HMAC signature. Any transformation of the request body — including charset conversion, normalization, or parsing into a framework-specific string type — can break verification. A byte-array overload would let developers verify the webhook against the exact raw request body, which is the safest approach for cryptographic checks.

Related Reference

A similar webhook signature verification issue has already been documented here Python SDK, Issue 65, where valid webhook signatures failed to verify in real-world setups.

I am happy to submit a PR for this if the approach is approved.

[sagar-rai]

@ankitdas13 @HarshLileshShah if you guys think this is a valid issue, I would like to create a pr for a new method and a fix and push for review in all the sdks, and update the documentation.

[Ilia01]

This looks like a real API gap.

Webhook signature verification should operate on the exact bytes that were received, not on a Java String that may already have gone through decoding or normalization. Special characters are exactly where that abstraction leaks.

So I think a byte[] or raw-payload overload is the right fix. At minimum I would:

• accept raw bytes for signature verification
• keep the current String API explicit about required encoding, probably UTF-8
• document that frameworks and middleware must preserve the original request body until verification is done

This is the same class of failure people hit with Stripe and GitHub webhooks in Node when a framework parses JSON before verification: the payload can still look correct in logs while the signed bytes are no longer identical.

I built HookLens around that exact debugging loop on the Node side, and the consistent rule has been: verify against raw bytes first, deserialize second.

So from an SDK/API-design standpoint, I would support adding the raw-byte variant here.

[IamPritamAcharya]

I’ve implemented a fix for this issue and opened a PR: #352.

The fix ensures consistent UTF-8 encoding for hashing and adds a byte[] overload to support raw payload verification.

Also added test coverage for multi-byte payloads.

Happy to make any changes based on feedback.