Open source · MIT · one binary

The chargeback arrives in 30 days. Or in 10 seconds.

TwinStub plays a third-party API back as a real HTTP server with memory: sessions, state, and chains of HMAC-signed webhooks with retries and a delivery journal. Run it in your terminal, in CI, or hand it to your coding agent.

Download
$ go install github.com/twinstub/twinstub/cmd/twinstub@latest
localhost:8080
$ curl -X POST localhost:8080/v1/orders/ord_42/payment \
-H 'X-TwinStub-Scenario: payment.chargeback' \
-d '{"amount": 1999}'
{"id": "pay_01J...", "status": "processing"}
t+3s -> webhook payment.succeeded signed, delivered
t+13s -> webhook payment.chargeback "reason": "fraudulent"
$ curl localhost:8080/v1/orders/ord_42/payment
{"status": "chargeback"} # the twin remembers

"The sandbox says: wait 30 days"

Chargebacks, KYC rejections and refunds can't be triggered on demand in most provider sandboxes. TwinStub moves a session's clock 30 days forward in one call and delivers everything due on the way.

"Your mock has no memory"

Real integrations are sequences: create, poll, webhook, poll again. A classic mock returns the same answer forever. TwinStub is a state machine with sessions, so the same GET says processing, then succeeded, then chargeback.

"Nobody tests webhooks honestly"

Signatures, retries, ordering, duplicates. TwinStub sends real HMAC-signed webhooks, delivers them in the order you choose, redelivers them, and breaks their signatures on purpose.

For coding agents

Your agent writes the handler. Now it can test it.

twinstub mcp gives an agent 13 tools: start a session, deliver completed before pending, redeliver an event, send a bad signature, move time 30 days forward, read what your app answered. The Claude Code plugin adds a skill that makes the agent write the expected end state first and check your app's state, not the 200s.

Claude Code with the TwinStub plugin checks a webhook handler and finds four failing cases
Claude Code with the plugin, asked only to "check the Acme Pay webhook handling of this service for edge cases". Every delivery got a 200; the bugs show only in the account state. Sped up 3x.
Claude Code
> /plugin marketplace add twinstub/claude-plugin
> /plugin install twinstub@twinstub

Other MCP clients run twinstub mcp directly. See the MCP docs.

How it works

Three steps, no framework

  1. 01

    Describe the provider in YAML

    States, replies, timed webhooks, signing. One file is the whole contract, and it lives in your repo.

  2. 02

    Run it

    twinstub serve locally or in CI, or let your agent start it through twinstub mcp.

  3. 03

    Point your code at the twin

    Call it, receive signed webhooks, reorder and replay them, then assert your own state, not the acks.

scenarios/payment_chargeback.yaml
# trimmed: webhook targets and bodies left out
scenarios:
- id: payment.chargeback
session: {key: "path:{order_id}"}
initial: new
states:
new:
on:
- when: {method: POST, path: "/v1/orders/{order_id}/payment"}
reply: {status: 201, body: '{"status": "processing"}'}
goto: processing
processing:
enter:
- webhook: {target: shop, event: payment.succeeded, after: 3s}
goto: succeeded
succeeded:
enter:
- webhook: {target: shop, event: payment.chargeback, after: 30d}
goto: chargeback
chargeback: {}

What you actually test

Your code, on the events that break integrations

Inbound webhooks

Does your handler verify the signature, reject a forged one, and answer 2xx so the sender stops retrying?

Idempotency

The same event delivered twice must settle once. TwinStub redelivers under a new delivery id, or sends a byte-identical duplicate.

Out-of-order delivery

completed can arrive before pending. Deliver queued webhooks in exactly the order you want to test.

Delays and faults

A chargeback 30 days later, a retry after your handler returned 503, a stalled or dropped connection.

One honest limit: a twin is only as accurate as the scenario you write. Confirm the response shapes once against the provider's own sandbox, then use TwinStub for the edge cases the sandbox can't produce.

Honest comparison

Where TwinStub wins, and where it does not

TwinStubWireMockMockoonBeeceptor
Stateful scenario chainsyes, first-classscenarios (flat states)limited (rules)no
Timed webhook chainsyes, with session clocksper-request callbackspartial (callbacks)basic callbacks
HMAC-signed webhooksyesmanual setupnono
Delivery journal and replayyesnonopaid
Tools for coding agentsMCP server, Claude Code pluginnonono
Single static binaryyesJVMElectron/CLISaaS
Record and proxy real trafficnoyes, matureyesyes
GUIno (by design)third-partyyes, greatyes
Protocol coverageHTTP/JSONHTTP incl. multipart, XMLHTTP, WS, gRPC proxyingHTTP

Need traffic recording, a GUI, or XML/SOAP matching? WireMock and Mockoon are better tools today. TwinStub's lane is deterministic, versionable simulation of event-driven APIs.

Get started

A single binary for macOS, Linux and Windows, or a Docker image. No account, no cloud.

$ go install github.com/twinstub/twinstub/cmd/twinstub@latest

Hosted sandboxes with a public URL and a live delivery journal: free beta coming soon.