2026 PLATFORMS Enterprise AI Agents, Custom ERPs & Programmatic SEO Deployments
Team Web India
FinTech Architecture • Webhook Reliability

Webhook Reliability & Idempotency: Cashfree, Razorpay & Shiprocket

Published: Nov 5, 2026
Category: FinTech & Logistics Architecture
Reading Time: 10 min read
Author: Team Web India Technical Pod

The Anatomy of a Failed Webhook Event

In high-volume e-commerce and SaaS billing, relying on the client-side browser redirect (e.g., the browser "Thank You" page) to mark an order as paid is a critical architectural vulnerability. If the customer closes the mobile browser tab before redirecting, your database never records the payment.

Webhooks solve this by pushing server-to-server notifications. However, network timeouts, duplicate gateway retries, and race conditions can cause double order fulfillment unless handled defensively.

Cryptographic HMAC-SHA256 Signature Verification

Never process a webhook without verifying the cryptographic signature passed in the HTTP request headers (`x-webhook-signature` or `X-Razorpay-Signature`). This guarantees the payload originated from your payment gateway and was not tampered with:

// app/Libraries/WebhookSecurity.php public static function verifyRazorpay(string $payload, string $signature, string $secret): bool { $expectedSignature = hash_hmac('sha256', $payload, $secret); return hash_equals($expectedSignature, $signature); }

Idempotency Keys & Database Atomic Locks

Every incoming webhook event possesses a unique transaction ID (`order_id` or `payment_id`). Before processing, the application must acquire an atomic database lock or check a dedicated `processed_webhooks` table:

CREATE TABLE webhook_events ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, event_id VARCHAR(100) NOT NULL UNIQUE, provider ENUM('razorpay', 'cashfree', 'shiprocket') NOT NULL, status ENUM('processing', 'completed', 'failed') NOT NULL, payload_json JSON NOT NULL, created_at DATETIME NOT NULL ) ENGINE=InnoDB;

If an insert into `webhook_events` violates the UNIQUE constraint on `event_id`, the controller immediately returns HTTP 200 OK without re-executing order fulfillment.

Automated Shiprocket Order Creation & AWB Generation

Once the payment webhook transitions to `completed`, an asynchronous job invokes the Shiprocket Custom Orders API. The system verifies postal PIN code serviceability, selects the lowest-cost or fastest courier partner (Delhivery, BlueDart, Ecom Express), generates the Airway Bill (AWB), and saves the tracking URL directly to the customer's order record.

Dead-Letter Queues & Daily Payment Reconciliation

If an internal error occurs (e.g., inventory table lock), the webhook event is pushed to a Dead-Letter Queue (DLQ) with an exponential backoff retry counter (1m, 5m, 15m, 1h). Furthermore, an automated nightly cron reconciles your database settlement balance against Cashfree and Razorpay settlement APIs, flagging any discrepancy greater than ₹0.00.

Frequently Asked Technical Questions

Why must webhook endpoints always return HTTP 200 OK quickly? +

Payment gateways expect an HTTP 200 acknowledgment within 5 seconds. If your server takes too long to execute heavy downstream tasks, the gateway assumes failure and retries the webhook, flooding your server with duplicate requests.

Can we test webhooks locally in development on Windows? +

Yes. You can use tools like ngrok or Cloudflare Tunnels to expose your local port securely to the payment gateway sandbox environment.

How does the system handle refund webhooks? +

Refund events (e.g., `refund.processed`) trigger automated reverse ledgers, notifying the accounting team and updating inventory stock if items were returned to the warehouse.

Technical Implementation

Implement This Architecture in Your Platform

Speak directly with our senior software architects. Receive a comprehensive architectural scope memo, database ERD design, and flat-fee estimate within 24 hours.

Call +91 96776 22025