Skip to main content
This walkthrough takes a Stripe handler running on your machine from a first captured event to a first finding. You need Node.js (for npx) or the installed binary, and a handler listening on localhost.
1

Get a capture URL

Open the example run and press Get a URL. This starts a guest session: no account, no email.
Example run page with the Get a URL button framed in magenta.

The example run page. Get a URL starts a guest session.

You land on Arrivals with your capture URL. Copy it.
Arrivals page waiting for the first delivery, with the capture URL framed.

Your capture URL, on the capture host in.webhooktrap.dev.

A guest session lasts 24 hours and holds up to 100 deliveries and 10 runs. The session bar shows the time left and both counts. One hour before the end it says Ends in 1 h, and a full quota says Limit reached. Sign in from the session bar to keep it: the session moves into your account, with the same URL and deliveries.
2

Send a webhook to it

The waiting panel has instructions per provider. For Stripe: in test mode, open Developers › Webhooks › Add destination, paste the URL, pick the events you handle, save, then trigger a test checkout.
Waiting panel with tabs for Stripe, GitHub, Shopify, Standard Webhooks and curl.

Provider instructions on the waiting panel.

Any HTTP request works too:
From your own app, set its webhook or callback URL (often an environment variable such as WEBHOOK_URL) to the capture URL and trigger the event.The capture URL always answers 200 with {"received":true}. See Capture endpoint.
3

See it arrive

Deliveries appear live. Webhook Trap recognises the provider from its headers and groups related events, here three Stripe events about one subscription.
Arrivals list with invoice.paid, payment_intent.succeeded and customer.subscription.updated, and the detail of the selected delivery.

Three Stripe events, grouped by subscription.

The signature shows Not checked: your signing secret stays on your machine, so only the agent can check it.
4

Pair the agent

Open Agent and press Pair an agent. The page shows a code, valid for 10 minutes, and the command to run.
Pair an agent panel with a 10-character code and the npx pair command framed.

A pairing code and its command.

Run it in a terminal on the machine where your handler runs:
The agent prints the server, the workspace, its name and its key fingerprint, then asks Join? [y/N]. Answer y only if you created the code in your own browser just now.
Agent 1.0.0 defaults to https://webhooktrap.dev when you leave out --server. Always pass --server https://app.webhooktrap.dev with 1.0.0. The default changes to the app host in a later release.
5

Declare your handler

In your project, create webhooktrap.yml. The agent only sends to the target declared here.
webhooktrap.yml
secret names an environment variable; the value never goes in the file. probe and reset are optional but turn on the state checks (Level 2). See Configuration.Start the agent from the same directory, with the secret in its environment:
6

Start a run

Select a delivery in Arrivals and press Prove, or Prove group to take every event of the group.
The Prove and Prove group buttons on a delivery, Prove group framed.

Prove one delivery, or the whole group.

Check the scenarios (1), the agent and target (2), and press Run (3).
Prove page with the scenario checklist, the connected agent and its target, and the Run button, numbered 1 to 3.

The run draft.

The first time, the agent asks in your terminal before it sends anything:
If webhooktrap.yml has cmd: probes or a reset, it lists those commands and asks once more.
7

Read the finding

The run page fills in as deliveries complete. The verdict line counts Critical, High and Medium findings and shows the exit code CI would get.
Run page with 2 findings, exit 1, and one cell per scenario.

The verdict and the scenario strip of a finished run.

Each finding says what happened, why it matters for this provider, and what to change. The fix names the deliveries that should behave differently on the next run.
Critical finding Accepts tampered payload with What happened, Why it matters, Likely cause, Fix and an Express snippet.

F1: the handler accepted a body it should have rejected.

Next steps

Test in CI

Commit fixtures and run webhooktrap test on every pull request.

Scenarios

What each scenario sends and what makes it fail.