Your integration's real bugs are in the events you can't trigger

lna_stub — Tue, 06 Oct 2026 10:26:21 +0000

Every integration I have written against a third-party API has the same shape.
The request/response part is easy and I get it right on day one. The failures show up later, in the branches that only run on rare events: the chargeback that lands a month after a clean payment, the KYC rejection, the webhook whose signature my code accepted without really checking, the callback that arrives out of order.

Those branches are exactly the ones a provider sandbox cannot help me exercise.
I cannot ask a real sandbox to charge back a payment on cue, or to deliver a webhook twice, or to send completed before I finished handling pending. And a classic mock server does not help either: it answers one request at a time with no memory, so it cannot represent "this payment already succeeded, now it is disputed".

So I wrote a small tool that treats an integration as what it actually is: a state machine.

The idea

You describe a scenario in YAML. A session remembers where a client is in the flow, keyed by whatever identifies it in your API - a body field, a header, a query or a path parameter. The same endpoint then answers according to the current state:

GET /v1/orders/ord_42/payment  ->  processing
   (a few seconds pass, a webhook fires)
GET /v1/orders/ord_42/payment  ->  succeeded
   (later, another webhook fires)
GET /v1/orders/ord_42/payment  ->  chargeback

Entering a state can schedule webhooks: delayed, HMAC-signed in the Stripe format, with retries, a delivery journal and replay. That is the part I care about most, because the webhook path is where my code has the most untested branches. Does the handler reject a forged signature? Does it answer 2xx so the sender stops retrying? Does the same event delivered twice settle once?

Two flags make it usable in CI. --time-scale compresses "30 days later" into seconds, so a full lifecycle runs in a test. --seed makes the template functions (ids, timestamps) reproducible, so snapshot assertions are stable.

What it is not

It does not record or proxy real traffic, and it has no GUI. If you need those, WireMock and Mockoon are the right tools. This one is aimed narrowly at deterministic, versionable simulation of event-driven APIs.

And there is one honest limitation worth stating up front: a twin is only as accurate as the scenario you write. If the YAML mismodels the real response, the twin will happily repeat your mistake. The workflow that works for me is to confirm the response shape once against the provider's own sandbox, then use the tool to drive the hundred edge cases the sandbox cannot reach.

Practical notes

It is a single Go binary. No cloud, no account, MIT licensed. Every miss returns a diagnostic 404 that lists the closest matchers and the reason each one was rejected, which turns "why didn't this match" from guesswork into reading. Hot reload does not break active sessions - they finish on the config version they started with. Outbound webhook delivery has an SSRF guard and never follows redirects.

Try it

TwinStub is one binary that talks HTTP, so your integration stays in whatever language it already is. Install it with Docker, a prebuilt binary, or Go:

docker run -p 8080:8080 -p 9090:9090 ghcr.io/twinstub/twinstub
# or: go install github.com/twinstub/twinstub/cmd/twinstub@latest
# or: download a binary from the Releases page

twinstub init demo && cd demo
twinstub serve

The generated project is the chargeback flow above. Repo, docs and a catalog of fintech scenarios: https://github.com/twinstub/twinstub

If you integrate with payment, logistics or CRM APIs, I would like to know where this model helps and where it breaks down for you.

DEV Community: lna_stub

Your integration's real bugs are in the events you can't trigger

The idea

What it is not

Practical notes

Try it