A 200 from your webhook handler proves nothing

November 12, 2026 · 5 min read

The most common webhook test looks like this: build a signed event, POST it to the handler, expect 200. It catches real problems: a parser that chokes on a field, a signature check that rejects valid events, a crash. What it cannot catch is the class of bugs that costs money: the handler accepted the event and then did the wrong thing.

Three handlers that answer 200 and are wrong

These come from a real test run on a small subscription service. Each delivery below was answered with 200, and each left the account in a wrong state.

The same event, twice. Providers redeliver: after a timeout, after a network error, after your server answered 503 during a deploy. A handler that adds credits on payment.completed without remembering the event id credits the customer twice. Both deliveries: 200.

The late event. payment.completed arrives, the customer gets access. Then the delayed payment.pending arrives and the handler sets the status back to pending. The customer paid and is locked out. Both deliveries: 200.

The old event. A customer’s first payment is charged back weeks later, after they have subscribed again and paid. The handler finds the account by customer id, not by payment, and revokes the new, paid subscription. Delivery: 200.

In all three cases the provider is satisfied. It only needs a 2xx to stop retrying. Your business needed something else.

The ack is the provider’s contract, not yours

A webhook response tells the sender one thing: “I have it, stop retrying”. That is worth testing, but it is the provider’s half of the contract. Your half is what happens to your data: the order, the ledger, the subscription, what the customer can do next.

So the assertion belongs on your state:

  • the account status, read back through your own API or database;
  • the balance or credits, as a number;
  • what the user can actually do: open the paid feature, download the invoice, see the shipment.

Write the expected end state first

Before running anything, write a table: the events in a given order, and the state your app should end in. Same events in a different order often mean a different expected result, which is the point.

Events, in this orderExpected state
pending, completedactive, 900 credits
completed, completed (redelivered)active, 900 credits
completed, pendingactive
completed, then chargeback 30 days laterrevoked, 0 credits
completed answered 503, then retriedactive, 900 credits, applied once
invalid or missing signaturerejected, account unchanged

Writing it first matters. If you run the handler and record what it did as the expected result, a snapshot test, you lock in the bug: 1800 credits becomes “correct” and the test stays green forever.

What a state assertion looks like

In Go, with the service under test running and events sent in a chosen order, the test reads the account back and compares fields:

func TestRedeliveredCompletedCreditsOnce(t *testing.T) {
	send(t, completed("evt_1", 900)) // first delivery
	send(t, completed("evt_1", 900)) // the provider redelivers the same event

	a := account(t, "u1")
	if a.Status != "active" || a.Credits != 900 {
		t.Fatalf("after a redelivery: %+v, want active with 900 credits", a)
	}
}

Note what is not asserted: the status codes of the two deliveries. They will both be 200 whether the handler is right or wrong.

Cover the axes, not just the events

Most handler bugs live on a few axes. A useful table has at least one row for each:

  • Duplicates: the same event id delivered twice must settle once.
  • Order: completed before pending; a refund before the capture notice.
  • Delay: the chargeback 30 days later, after other things changed.
  • Failure and retry: your handler answers 5xx mid-change, the provider retries. Applied once, not zero times and not twice.
  • Signatures: invalid and missing ones are rejected and change nothing.

And every time production surprises you, add the surprise as a row. The list of cases nobody tested shrinks quickly once incidents become fixtures instead of memories.

Producing the sequences

The hard part is usually not the assertion. It is getting the provider to send events in the order and timing you need: most sandboxes cannot send a chargeback on demand, deliver completed before pending, or redeliver an event that was already accepted.

That is what TwinStub is for. It plays the provider: your app calls it like the real API, and it sends signed webhooks from a stateful scenario. Through its admin API, or through MCP tools for a coding agent, you deliver queued events in any order, redeliver them, break their signatures, and move a session’s clock 30 days forward. The assertion stays yours: TwinStub produces the sequence, your test checks your state.

Where these ideas came from

Not from us alone. They took shape in the discussion under the TwinStub announcement on dev.to. Muhammad Turner Gane argued for checking what the user can access after the whole lifecycle instead of the status codes, and for a table of expected end states instead of snapshots. challan116-ux, who works with EDI integrations, described saving every failed document as a permanent regression test; the phrase “fixtures instead of memories” is theirs. Thank you both.