💳 Implementing Razorpay Webhooks in Spring Boot 🚀 Real Problems I Faced & How I Solved Them

Building a payment integration is easy in a tutorial.
Making it actually work is where the real engineering begins. 😅

While working on my ShopEase e-commerce project, I reached a point where payment creation and verification were already working. The next challenge was handling Razorpay Webhooks and processing payment events asynchronously.

🏗️ My Payment Architecture

ShopEase uses a microservices-based backend, with a separate payment-service running on port 8085.

🔄 Before Webhooks
🛒 Frontend
↓
🌐 API Gateway
↓
💳 Payment Service
↓
💰 Razorpay
⚡ After Adding Webhooks
💰 Razorpay
↓
🔔 Webhook
↓
💳 Payment Service
↓
🔐 Verify Signature
↓
🔎 Identify Event
↓
🗄️ Update Payment
↓
💾 Store Event ID
😵‍💫 Challenge #1 — Duplicate Webhooks

One of the first things I realized was that a webhook may be delivered more than once.

If I process the same event twice, I could accidentally execute the same business logic multiple times.

So I introduced a webhook_events table and stored the webhook's eventId.

🔐 Why?
Webhook received
↓
Already processed?
↙ ↘
YES NO
↓ ↓
Ignore Process
↓
Save Event ID

This gave my webhook processing idempotency.

🔑 Challenge #2 — Webhook Secret ≠ API Secret

This one was important.

I learned that the Razorpay Webhook Secret is different from the Razorpay API Key Secret.

Instead of hardcoding the secret, I kept it in an environment variable:

razorpay.webhook.secret=${RAZORPAY_WEBHOOK_SECRET}

🔒 Never put actual secrets directly into your GitHub repository.

🛡️ Challenge #3 — Verifying the Webhook Signature

I couldn't simply trust every request that reached my endpoint.

The request contains:

X-Razorpay-Signature

I used Razorpay's signature verification mechanism with the raw request payload and my webhook secret.

📨 Incoming Request
↓
🔐 Extract Signature
↓
🧮 Generate/Verify HMAC
↓
Valid? ────── No → ❌ Reject
↓
Yes
↓
✅ Process
🚫 Challenge #4 — The Mysterious 403 Forbidden

This was one of those errors where I initially thought:

"Controller mein hi kuch problem hai." 😅

But the controller wasn't the problem.

Spring Security was blocking the request.

My normal APIs require authentication, but Razorpay's webhook doesn't have my application's JWT.

So I specifically permitted:

.requestMatchers("/payments/webhook").permitAll()

and disabled CSRF for the API.

💡 Lesson

A perfectly written controller is useless if security blocks the request before it reaches the controller.

🧪 Challenge #5 — Testing Without Razorpay

While testing locally through Postman, I initially didn't have the real Razorpay signature.

A fake signature such as:

test-signature

correctly resulted in:

401 Unauthorized

And honestly, that was good news. 😂

It meant my signature verification was actually doing its job.

So I created a Postman Pre-request Script to generate the HMAC-SHA256 signature automatically whenever I changed the webhook payload.

🫠 Challenge #6 — "Payment Record Not Found"

This was probably one of my most interesting debugging moments.

The signature was valid ✅
The event was recognized ✅

But:

{
"success": false,
"message": "Payment record not found"
}
🔍 Root Cause

The Razorpay Order ID didn't match the Order ID stored in my database.

It was literally a tiny character difference. 😭

Postman:
order_TT9CFIQhKkyXwR

Database:
order_TT9CFlQkHkyXwR

For humans, they look almost identical.

For a database?

Completely different values. 💀

After correcting the Order ID, the webhook successfully found the payment.

🐳 Challenge #7 — XAMPP vs Docker MySQL

This one caused a lot of confusion.

My application was using:

localhost:3308

while I was checking MySQL through XAMPP/phpMyAdmin on:

localhost:3306

I eventually discovered that port 3308 was actually mapped to my Docker MySQL container:

Windows :3308
↓
🐳 Docker
↓
MySQL :3306

The container was:

shopease-mysql
mysql:8.4
0.0.0.0:3308 → 3306

So instead of trying to move XAMPP to port 3308, I connected directly to the Docker MySQL container.

🧠 Biggest Lesson Here

Before changing a port, first find out which process is already using it.

✅ Testing payment.captured

After fixing the database issue, I tested:

payment.captured

The webhook returned:

{
"success": true,
"message": "Webhook signature verified",
"event": "payment.captured"
}

with:

HTTP 200 OK

More importantly, I didn't stop at the API response.

I checked the database and confirmed:

CREATED
↓
SUCCESS

That confirmed the actual business logic worked, not just the HTTP response.

🔁 Testing Idempotency

Then came the real test.

I sent the exact same webhook again using the same event ID.

Instead of processing it again, the application returned:

{
"success": true,
"message": "Webhook already processed",
"event": "payment.captured"
}

🎯 Duplicate processing successfully prevented!

❌ Testing payment.failed

I also tested:

payment.failed

The webhook was successfully processed and the database payment status changed to:

FAILED

So both major payment events were working:

Event Result
💰 payment.captured ✅ SUCCESS
❌ payment.failed ✅ FAILED
🔁 Duplicate event ✅ Blocked
🔐 Invalid signature ✅ Rejected

🏁 Final Architecture
💰 Razorpay
│
│ 🔔 Webhook
↓
POST /payments/webhook
│
↓
🛡️ Spring Security
│
↓
🔐 Signature Check
│
↓
🔎 Event Detection
↙ ↘
payment.captured payment.failed
↓ ↓
Find Payment Find Payment
↓ ↓
SUCCESS FAILED
↘ ↙
↓
🔁 Check Event ID
↓
Already Processed?
↙ ↘
YES NO
↓ ↓
Ignore 💾 Save Event
↓
✅ 200 OK

🧠 What This Actually Taught Me

The biggest lesson wasn't just "how to implement Razorpay Webhooks."

It was learning how to debug a complete backend system.

🔐 1. Security matters

A controller can't help if Spring Security blocks the request.

🎯 2. IDs must match exactly

A single character difference can break a database lookup.

🐳 3. Understand your infrastructure

Docker port mapping can completely change where your application is actually connecting.

🔁 4. Webhooks must be idempotent

The same event shouldn't execute your business logic multiple times.

🗄️ 5. Verify the database

200 OK doesn't necessarily mean your business logic worked.

🐛 6. Debugging is part of development
💻 Code
↓
🧪 Test
↓
❌ Error
↓
🔎 Find Root Cause
↓
🔧 Fix
↓
🧪 Test Again
↓
🗄️ Verify Database
↓
✅ Done

🚀 Current Status

My Razorpay Webhook implementation currently supports:

✅ Webhook endpoint
✅ Signature verification
✅ payment.captured
✅ payment.failed
✅ Payment status updates
✅ Duplicate webhook detection
✅ Idempotent processing
✅ Database verification

The next step is to extend the webhook flow beyond payment status updates and connect it with the complete post-payment business logic, such as order confirmation and cart clearing.

💡 Final Takeaway

Implementing Razorpay Webhooks taught me something important:

Real-world backend development isn't just about writing code. It's about understanding what happens when that code meets security, databases, infrastructure, external APIs, and unexpected errors.

The most valuable part of this implementation wasn't simply making the webhook work.

It was debugging:

403 errors → invalid signatures → incorrect Order IDs → Docker/MySQL conflicts → duplicate events → database verification. 😎🔥

And that's what made this feature much more realistic than simply following an integration tutorial.

🛒 ShopEase — Payment Service
💳 Razorpay Webhook Integration 🚀

Learn → Build → Break → Debug → Fix → Improve. 💻🔥