stuntman / providers / webhook inboxes

Webhook inboxes

Endpoints your app sends its own webhooks to, answering however you need to test its retries.

Stands in for

  • Your customers' webhook endpoints
  • HMAC-signed webhooks (t=…,v1=… and plain hex or base64)

Everything Webhook inboxes gives you

  1. 01

    Every delivery kept

    Headers, body, signature check, the answer given and every attempt of the same event, newest first.

  2. 02

    Answer as you choose

    Always 200, accept with 202, always an error, fail N times then succeed, fail a share, hang, reset or an empty reply.

  3. 03

    Retries per event

    fail_then counts per event id or per inbox, so each event fails 3 times and the attempts show the app's backoff.

  4. 04

    Delays and hangs

    Add a delay before answering, or hold the request: 35 s tests a 30 s client timeout.

  5. 05

    Signature checks

    t-v1-hmac-sha256, hmac-sha256-hex or hmac-sha256-base64, with a timestamp tolerance and a replay check on the event id.

  6. 06

    Secret rotation

    Set previous_secret: a delivery signed with the old secret is marked as such. reject_bad answers 401 like a strict customer.

  7. 07

    Traps for the client

    A redirect to a private address (SSRF), a 50 MB answer, or one byte a second: each recorded as passed or failed.

  8. 08

    Ephemeral inboxes

    A test or an agent makes an inbox that expires by itself (1 h by default); kept ones live in webhooks/inboxes.yaml.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

Deliveries and their checks

Deliveries and their checks: the Webhook inboxes screen in Stuntman
1Ephemeral inboxes

Made by a test or an agent; each shows when it expires and who made it.

1 of 5
2Old secret

Signed with the previous secret: the app is still using it after rotation.

2 of 5
3Duplicate

The same event id seen before: the app sent it twice.

3 of 5
4Old timestamp

Signed, but the timestamp is outside the tolerance (5 min by default).

4 of 5
5Signature

Which scheme, which secret, the timestamp age and whether the id is new.

5 of 5
  1. Ephemeral inboxes

    Made by a test or an agent; each shows when it expires and who made it.

  2. Old secret

    Signed with the previous secret: the app is still using it after rotation.

  3. Duplicate

    The same event id seen before: the app sent it twice.

  4. Old timestamp

    Signed, but the timestamp is outside the tolerance (5 min by default).

  5. Signature

    Which scheme, which secret, the timestamp age and whether the id is new.

How an inbox answers

How an inbox answers: the Webhook inboxes screen in Stuntman
1Mode

Fail N times then succeed; also always 200, 202, error, a share, hang, reset or empty.

1 of 5
2Count per event id

Each event fails 3 times, not the inbox as a whole.

2 of 5
3Hang

Hold the request: 35 s tests a client that gives up at 30 s.

3 of 5
4Traps

Private redirect, huge answer, slow answer: the app should not follow, should cap and give up.

4 of 5
5Attempts

Each attempt of the last event and the gap before it: the app's backoff, measured.

5 of 5
  1. Mode

    Fail N times then succeed; also always 200, 202, error, a share, hang, reset or empty.

  2. Count per event id

    Each event fails 3 times, not the inbox as a whole.

  3. Hang

    Hold the request: 35 s tests a client that gives up at 30 s.

  4. Traps

    Private redirect, huge answer, slow answer: the app should not follow, should cap and give up.

  5. Attempts

    Each attempt of the last event and the gap before it: the app's backoff, measured.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • Fail then succeed

    Each event gets 500 three times, then 200

    set_inbox mode fail_then, times 3
  • Fail a share

    A percentage of deliveries fail

    set_inbox mode fail_share, share 50
  • Always an error

    Every delivery gets the status you pick

    set_inbox mode error, status 503
  • Hang

    No answer until the app gives up

    set_inbox mode hang
  • Reset

    The connection is reset

    set_inbox mode reset
  • Empty reply

    The connection closes without a byte

    set_inbox mode empty
  • Slow answer

    A delay before every answer

    set_inbox delay
  • Private redirect

    302 to a loopback address: does the app follow?

    set_inbox traps redirect_private
  • Huge answer

    A 50 MB body: does the app stop reading?

    set_inbox traps huge
  • One byte a second

    Does the app give up on a slow answer?

    set_inbox traps slow
  • Strict customer

    Bad signatures get 401

    set_inbox reject_bad true
  • Inbox gone

    Later deliveries get 410 Gone

    remove_inbox

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Check that the app retries an order.completed webhook three times with backoff and signs it correctly.

create_webhook_inbox{"name": "globex", "fail": 3, "then": 200, "secret": "whsec_test"}
→ ok http://localhost:8027/in/globex · expires in 1h
wait_for_delivery{"inbox": "globex", "event": "order.completed", "timeout": "15m"}
→ ok 4 attempts: 500, 500, 500, 200 · gaps 1, 3, 9 min · signature valid

MCP tools

  • create_webhook_inboxAn inbox, ephemeral by default
  • set_inboxHow it answers, traps and signature settings
  • list_webhook_inboxesKept and ephemeral inboxes with their URL
  • get_webhook_inboxBehaviour, signature and the last event's attempts
  • list_deliveriesDeliveries with signature result and answer
  • get_deliveryHeaders, body, checks and all attempts
  • wait_for_deliveryWait until a delivery is answered
  • remove_inboxRemove an inbox; later deliveries get 410

The same over HTTP

  • POST/api/webhooks/inboxes
  • PUT/api/webhooks/inboxes/{name}
  • GET/api/webhooks/deliveries
  • GET/api/webhooks/deliveries/wait
  • DELETE/api/webhooks/inboxes/{name}