Idempotent payment webhooks in Laravel: stop duplicate orders from LiqPay and Monobank

Duplicate orders quietly cost you money. A customer pays once, but your store records two orders, ships twice, or double-charges — then handles the refund, the support ticket, and the lost trust. The root cause is almost always a payment webhook processed more than once.

LiqPay and Monobank both retry callbacks. If your endpoint times out, returns a slow 500, or the network blips, the provider sends the same notification again — sometimes several times. Without protection, each retry creates another order row and fires your fulfillment logic again.

The fix is idempotency: process each payment event exactly once, no matter how many times it arrives.

## How we build it in Laravel

We treat the provider's transaction identifier as an idempotency key. For LiqPay that is the order_id plus payment status; for Monobank it is the invoiceId from the acquiring API.

1. Store processed events. A small payment_events table holds the idempotency key with a unique index. The database, not your code, becomes the source of truth.

2. Wrap the handler in a transaction. Inside a DB::transaction, we insert the key first. If the unique index rejects it, the event was already handled, and we exit early with a 200 OK.

3. Verify the signature before anything else. We validate the LiqPay signature and the Monobank X-Sign header, so only genuine callbacks reach the order logic.

4. Return 200 fast. We acknowledge receipt immediately and push heavy work — invoices, Nova Poshta shipping labels, email — onto a queue. Slow responses are what trigger retries in the first place.

The result: a customer can refresh checkout, a provider can retry ten times, and your store still creates one order, charges once, and ships once.

## Why it matters for your bottom line

Idempotent webhooks remove a whole class of refunds, double shipments, and reconciliation headaches from your operations. The pattern is the same whether you run a Laravel store, a WooCommerce site, or an OpenCart shop with a custom payment bridge — reliable payment handling protects revenue and your reputation.

We have built and hardened payment integrations for LiqPay, Monobank, and international gateways across 20 years of production systems.

Need bulletproof payment handling for your store? Talk to MaxiMoruM: https://maximorum.com/