Webhook Reliability & Idempotency: Cashfree, Razorpay & Shiprocket
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.
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.