The payment webhook fired twice. The money moved once.

1 · You

You type one sentence.

Open your coding agent in a project that has almost nothing in it. Type: make this payment webhook handler safe to retry: the provider may deliver the same event more than once.

A webhook is a message your payment provider sends to your server when something happens, such as “payment succeeded”. If your server is slow to answer, the provider sends it again. Handle that message twice and the customer is credited twice.

Idempotent is the word for what you want. It means: doing it twice has the same result as doing it once. “Safe to retry” and “idempotent” are the same ask. Without a recipe, an agent writes something plausible from memory, and nothing says whether it survives a retry.

2 · Your agent

Your agent asks MM3 how.

You do nothing. Your agent sends your sentence to MM3 and a recipe comes back. It works out the language by itself, from package.json.

The one rule that matters: the handler remembers an event by the event’s own id, the one the provider prints on the event. Not by the delivery id, which the provider makes up again on every attempt.

The name is ours. Nobody calls this an “idempotent handler”. Bobby Woolf’s Enterprise Integration Patterns calls it an Idempotent Receiver; Chris Richardson’s microservices.io and Microsoft’s Azure guide call it an Idempotent Consumer. They also stretch it differently. Azure says “This pattern applies idempotency to message consumers”, then adds that the idea helps “any operation that runs more than once”; Stripe and the web standard RFC 9110 talk about repeated requests. A webhook is both a message and a request, so the recipe picks one handler and one stable key, and says so in its own first lines.

3 · Your agent

It writes the code, in your language.

Still nothing for you to do. The agent writes the files the recipe names and runs the demo: the same event arrives twice, the balance stays at 10, and the second delivery gets the first answer back. The key line is highlighted.

Two small gaps the agent reported back. The recipe’s file list shows a neutral name (key_store) where TypeScript wants key-store.ts, and one step asks a question a terminal agent cannot answer. It followed the TypeScript names, used the project folder, and told MM3, so the recipe can be fixed for the next person.

// Idempotent credit handler: a repeated message (same messageId) has the effect of one.// The key is the producer's messageId, never the broker's deliveryId.import { KeyStore } from "./keys/key-store.ts";import { Ledger } from "./ledger/ledger.ts";export interface CreditMessage {  messageId?: string;  deliveryId: string;  account: string;  amount: number;}export function handleCredit(store: KeyStore, ledger: Ledger, request: CreditMessage): string {  const key = request.messageId;  if (!key) throw new Error("missing message id");  if (!store.claim(key)) {    return store.outcome(key) ?? "duplicate in progress";  }  try {    const next = ledger.credit(request.account, request.amount);    const outcome = `credited ${request.account} balance ${next}`;    store.complete(key, outcome);    return outcome;  } catch (err) {    store.release(key);    throw err;  }

4 · Your agent

It proves it with a test.

You ask one more thing: write a test that delivers the same event twice and proves only one charge happens; run it.

The test sends event evt_1 twice, the way a provider retries: the same event id, and a new delivery id the second time. It passes: the balance is 10, and the second delivery returns the first answer.

Two ids, easy to mix up. The event id is printed by the provider on the event and never changes. The delivery id is made up fresh for every attempt to deliver it.

// Delivers the same payment event twice the way a webhook provider retries it// (same messageId, new deliveryId) and checks that only one charge happens.import { test } from "node:test";import assert from "node:assert/strict";import { handleCredit } from "../handler.ts";import { KeyStore } from "../keys/key-store.ts";import { Ledger } from "../ledger/ledger.ts";test("a redelivered event credits the account once and returns the first outcome", () => {  const store = new KeyStore();  const ledger = new Ledger();  const first = handleCredit(store, ledger, {    messageId: "evt_1",    deliveryId: "delivery-1",    account: "a1",    amount: 10,  });  const second = handleCredit(store, ledger, {    messageId: "evt_1",    deliveryId: "delivery-2",    account: "a1",    amount: 10,  });  assert.equal(ledger.balance("a1"), 10);  assert.equal(second, first);  assert.equal(first, "credited a1 balance 10");});

5 · MM3

MM3 checks it.

You say yes to one paid check (we said yes, once). The result, run MM3-0391: unsure. Good code, but not a clean pass, and that is worth reading.

The check is a fixed list of 21 questions: 18 yes/no, one overall goal, two judgement calls. The goal passes (0.80), and five of the six groups of questions pass. The sixth, “race”, asks whether two deliveries could slip past each other. It was only 61% sure that a plain in-memory “check, then add” cannot be interrupted.

The questions are locked with a fingerprint, so nobody can reword them to make a result come out better. The check cost about $0.00007 (estimated from tokens).

Our reading: that doubt is fair. In one Node process nothing can interrupt those two lines, and the file says so in a comment. But a real service runs several processes, and the database should be the one to refuse a duplicate. Azure’s guide says it this way: “Use a uniqueness constraint on the deduplication key such that two transactions can attempt to insert a key, but only one can succeed.”

6 · Try it

Is it just saying yes? Change one word.

A check that always says yes is worthless. So we made a copy of the handler with exactly one word changed: it takes the delivery id as the key instead of the event id. Everything else is the same. It still has a key store, still claims before it credits, still gives the key back on failure. Flip the switch to do it yourself.

We also deleted the comment that stated the rule, so nothing in the file gives the answer away. Watch the two key questions fall (Q1 and Q10) while the others hold: Q5, a repeat gets the first answer, stays at 0.87. Two more fall that the panel does not show: because a delivery id is never missing, the handler no longer refuses an event that has no event id (Q2 0.34, Q11 0.35).

export function handleCredit(store: KeyStore, ledger: Ledger, request: CreditMessage): string {  const key = request.messageId;  if (!key) throw new Error("missing message id");  if (!store.claim(key)) {    return store.outcome(key) ?? "duplicate in progress";  }

7 · The twist

Why the obvious test passes it.

Why would a good test pass the broken copy? Because of how the test retries. Send the event twice and watch the balance. With the good copy, a retry changes nothing. With the one-word copy, a retry that arrives with a new delivery id, which is what a real provider sends, credits again. A retry that reuses the delivery id, which is what a quick test often does, looks fine.

8 · The result

What it comes to.

One sentence from you, and one follow-up. A recipe with its sources. A handler that credits once, and a test that proves it. And a check that read the code and flagged the one word the obvious test could not see.