Idempotency Explained for Business Systems

A customer clicks pay twice. A webhook arrives twice because the sender never got your acknowledgement. An automation restarts and runs the same step again. If any of those create a second invoice, a second email, or a second charge, the repeat was treated as new work.

The call may fail halfway, or succeed and lose the response. Both look like silence to the sender. A retry is reasonable only if a second delivery does not repeat the side effect.

Idempotency explained in plain English

Idempotency means that doing an operation once, or several times with the same intent, leaves the business in the same state.

“Set the order status to paid” is idempotent. The second time, the status is already paid. “Add a line to the invoice” is not. The second time, you have two lines. “Send the receipt” is not, unless you have recorded that this receipt has already gone.

A second run that only says “already exists”, with no link to the first result, can still send the caller down a different path. Amazon’s guidance is to return a response that means the same thing as the first success, for as long as you remember the request.

Why the same request arrives twice

People double-click. A flaky connection drops the response and the app tries again. A webhook provider retries when your endpoint is slow to answer. How that delivery works is in webhook fundamentals. A workflow restarts after a deploy and picks the same item up again.

This is ordinary life for an API integration. A retry strategy makes repeats more common on purpose. If the step is not safe to run twice, the recovery path is what creates the duplicate.

Do not infer a duplicate from identical fields. Two requests with the same settings may be two real jobs. Amazon’s preferred contract is an explicit identifier from the caller.

What a repeat does to the business

The harm shows up in the inbox first. A second invoice. A second confirmation email. A second contact in the CRM. A count reduced twice, so a later order is refused while the goods are still there.

A retry of a charge that is not idempotent can double-charge. That is a property of the operation, not a case study, and not a claim about any payment provider. Ask whether a repeated request with the same reference is one charge or two, and test it. Idempotency does not clear genuine exceptions. It stops the ordinary repeat from becoming one.

Four patterns that keep a repeat safe

An idempotency key. The sender generates a unique identifier for this attempt at this job and sends it with the request. The receiver stores the key with the outcome. A later request with the same key returns the stored outcome instead of doing the work again.

Stripe accepts a key on create and update requests, up to 255 characters. Use a random value, such as a UUID, not an email or other personal identifier. The key will sit in logs, which is a GDPR concern as well as a collision risk.

On API v1, Stripe saves the first status and body once the endpoint has started, and a retry returns that saved response, including a 500. Keys can be removed after at least 24 hours. A reused key after that is a new request. The newer API version does not simply replay the first response in every case. Read the contract for the version you call.

Illustration only. The value is made up, and this is not a live request:

Idempotency-Key: 4f1c0b2e-9a7d-4c3a-8e21-6b0d5a1f9c33

If the same key comes back with a different amount or a different customer, refuse it. Stripe compares the parameters and errors when they differ. Amazon does the same with a client request token. Applying the new details quietly would hide a bug in the sender.

A check before the side effect. Before you create, send, or charge, ask whether this job is already done. If yes, return the existing result. The check and the write need to happen together. If you record the key and then fail to do the work, or do the work and fail to record the key, the next retry is blind.

Set, don’t add, where the meaning allows it. “Set status to dispatched” can be repeated. “Add 1 to a count” cannot. Use the set form when the meaning is “make it so”, not “do it again”.

A window, not a forever memory. You cannot keep every key indefinitely. Decide how long a repeat is still the same job: long enough to cover the sender’s retry schedule, not forever. After that, a repeated key is a new request, and the process should say so.

Where the check has to live

Put it on any step where a duplicate is visible to a customer or hard to undo.

Payments: the charge, and the “payment received” email that follows.
Invoices and orders: creating the record, not only updating its status.
Notifications: confirmation, dispatch, and “we tried to reach you”.
Webhooks: a repeated delivery of the same event is one event.
Counts: “subtract 1” is not idempotent. “This order has already reduced the count” is the check.

One key on the first step does not make a multi-step run safe. If a later step sends an email with no record of having sent it, a replay still sends it twice.

A test you can run this week

Run one real operation twice with the same key and the same details. The second run should hand back the first result, not a second record, email, or charge.

Then change one field and keep the key. That must fail, not quietly update the first job. Drop the first response in a test, and confirm the caller can retry without a duplicate. If you cannot, you do not yet know whether a lost response is safe.

Write that check into the procedure, including who is told when the same key arrives with different details.

AI systems work at Fernside is scoped workflow automation and integrations, measured in weeks, not a switch you turn on the same week. If you are not sure which steps must be safe to run twice, an advisory conversation can map them and compare what your tools already offer. That is scoping, not a date by which every repeat is harmless.

If you are not sure what a repeated webhook does to an invoice, an email, or a charge, book a discovery call and bring one example. We can look at where a second delivery would create a second outcome.