A 200 from your webhook handler proves nothing
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 order | Expected state |
|---|---|
pending, completed | active, 900 credits |
completed, completed (redelivered) | active, 900 credits |
completed, pending | active |
completed, then chargeback 30 days later | revoked, 0 credits |
completed answered 503, then retried | active, 900 credits, applied once |
| invalid or missing signature | rejected, 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:
completedbeforepending; a refund before the capture notice. - Delay: the chargeback 30 days later, after other things changed.
- Failure and retry: your handler answers
5xxmid-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.