Skip to main content

Integration pattern

Reviewed 14 October 2026

The same webhook twice should book one payment.idempotent webhook handler

Gateways send a webhook again when they do not hear back in time. If your handler books a payment each time, the ledger doubles.

No live demo shows a webhook yet. The sandbox below is the demo.

Use it when

  • A webhook creates or changes money, stock or a document.
  • The sender retries, as Razorpay, Stripe, Shopify and Frappe all do.
  • Your handler can fail after doing part of its work.

Skip it when

  • The handler only sets a value, such as "status = paid". Repeating it changes nothing, so a key table adds cost, not safety.
  • The webhook only sends a notification where a repeat is harmless, such as a chat message.
  • Only a few events arrive a month and a person checks each one against the bank statement.

Try it

Duplicate-delivery sandbox

Fire one payment event at a handler more than once. Change the handler and fire it again. Sample data. Not a measurement.

The event
From the gateway to your handler
payment.captured
Payment id
pay_SAMPLE1
Amount
₹12,000
For invoice
SINV-SAMPLE, ₹12,000

Why it arrives again

A Frappe Webhook waits 5 seconds by default, then sends again at once. Razorpay names the server that "accepts the event but fails to respond in 5 seconds". Shopify allows five seconds for the whole request. Stripe asks for a 2xx before any complex logic.

Frappe webhook.py, v15Razorpay best practicesShopify duplicate webhooksStripe webhooks

Times it arrives

Your handler

How it books the payment

Only matters for handlers that claim an id.

A bare receipt has no invoice rows, so ERPNext's allocation check never runs. When on, the handler allocates the full amount from the event each time.

What the handler did

3 receipts booked. The books show ₹36,000 in; the gateway paid ₹12,000. ₹24,000 sits unallocated.

  1. Arrival 1

    Booked a receipt

  2. Arrival 2

    Booked a receipt

  3. Arrival 3

    Booked a receipt

Receipts booked
3
Cash received per the books
₹36,000
What the gateway paid
₹12,000
Difference
+₹24,000
Unallocated receipts
₹36,000

Sample data. Not a measurement. A model of the pattern, not of any one gateway.

The four handlers at a glance

The four handlers at a glance: three arrivals, one after another, a bare receipt
HandlerWhat it doesReceipts
Books a receipt every time3 receipts booked. The books show ₹36,000 in; the gateway paid ₹12,000. ₹24,000 sits unallocated.3
Looks for an existing receipt, then booksOne receipt. The first arrival books; later ones find it and stop.1
Claims the event id, then booksOne receipt. Later arrivals find the id and stop.1
Claims the id and books in one transactionOne receipt. If the server stops, the id and the work roll back together, and the retry books once.1

Three arrivals, one after another, a bare receipt. Sample data.

What you give up, and how it fails.

Three trades, then five ways it breaks. Pick one for why, and the source.

  • Any number of repeats books once.What it costs: A table of event ids to keep, with a unique rule.
  • Retries become safe, so you can reply fast and work later.What it costs: Ids must outlive the sender's longest retry window, and any manual resend.
  • A stop midway leaves nothing half done.What it costs: The id row and the books must share one database, or you need a second safeguard.

How it fails

Documented

A Frappe Webhook waits 5 seconds by default and sends again at once after a timeout. Razorpay and Stripe say the same thing differently: reply fast, work later.

Documented

A Frappe Webhook waits 5 seconds by default and sends again at once after a timeout. Razorpay and Stripe say the same thing differently: reply fast, work later.

Each failure is Documented, with the maker's own page or code, or it Follows from the design. None is a result from a MithTech client project.

In ERPNext and Frappe.

Eight parts, each at a named version. Open one for what it does; build it in five steps.

Read from Frappe v15.123.0 and v16.52.0, ERPNext v15.122.0 and Frappe's payments app at commit 9885a6e5 on 14 October 2026, with the file and line. Other systems' names and settings were not checked here.

Integrations › Webhook

Sends in a background job after the save commits. Three attempts. Timeout 5 seconds unless you set one. After a read timeout the next attempt starts at once; after other errors it waits 1 second, then 4. One Webhook Request Log row per attempt. No delivery id in the request.

Frappe webhook.py, v15

How to build it

  1. Reply first. Return a 2xx as soon as the event is saved or queued; do the work after.

  2. Use the key the sender gives you: Razorpay's x-razorpay-event-id, Shopify's X-Shopify-Webhook-Id, Stripe's event id. If the sender gives none, as a Frappe Webhook does not, add the document name and modified time to the payload.

  3. Store the key with a unique rule, in the same transaction as the work. Let the insert decide, not a check before it.

  4. Make the work itself safe to repeat where you can: set a status, look up before you create.

  5. Keep keys at least as long as the sender can resend. Then reconcile for what never arrived.

Questions about idempotent webhooks

The one most people ask is answered first. Type to find the rest.

Why am I receiving duplicate webhooks?

Senders deliver at least once. If your server is slow, loses its reply or returns an error, the sender sends the event again: Razorpay for 24 hours, Shopify eight times over four hours, Stripe for up to three days, and a Frappe Webhook three times. Treat every event as something you will see more than once.

Start with one conversation

One message, call or WhatsApp is enough. Every line reaches the team directly.

Team away now