Workspaces and projects
Everything you capture and run lives in a project. A project has one capture URL, its own quotas and its own retention settings. Projects belong to a workspace: your account has one, and a guest session has its own. With an account you can create several projects from Projects › New project.
Creating a project.
Captures
A capture (shown as a delivery in the app) is one HTTP request received on a capture URL, stored as it arrived: method, path and query, headers, source address and the exact body bytes. Bodies up to 5 MiB are kept; for a larger body only its size and SHA-256 are kept. Credential headers such asAuthorization and Cookie are replaced before storage. See Capture endpoint.
Webhook Trap reads each capture with the provider’s pack: it detects the provider from its headers, reads the event type and id, and puts related events in a group, for example every Stripe event about one subscription.

Arrivals: deliveries grouped by the subscription they belong to.

A delivery: request facts, raw and decoded views.
Guest sessions
You can use Webhook Trap without an account. A guest session is created when you press Get a URL on the example run. It is a random token in a cookie and holds one project.
The guest session bar: time left, deliveries and runs used.
The agent
The agent is thewebhooktrap binary running on your machine. It is the only part that sends requests to your handler. It:
- pairs once with a server using a code from your browser, and keeps one Ed25519 key per server origin;
- connects out to the server and waits for runs; it opens no listening socket;
- sends deliveries only to the target declared in
webhooktrap.yml, after you approve that target once in the terminal; - signs deliveries with your secret, read from an environment variable. The server learns the variable’s name, never its value;
- runs your probe and reset commands, and reports only display forms of the readings.

Agents paired with your account.
webhooktrap test, which needs no server and no pairing. See CLI.
Runs
A run replays selected events (1 to 5, from one provider) against one target, in a fixed set of scenarios. It is planned before the first delivery and sends at most 50 deliveries. Every delivery carriesWebhooktrap-Run, Webhooktrap-Delivery, Webhooktrap-Scenario and Webhooktrap-Dry-Run: 1 headers, so your handler can recognise a test delivery.
A run is judged at two levels:
Without a probe, a scenario where every delivery got a 2xx is Inconclusive: the status codes can’t show whether a duplicate wrote twice.
A run ends with one status: Couldn’t start, Aborted, N findings, Inconclusive or Passed. Runs are private to the project’s owner. See Findings and exit codes.

Runs of a project.
Scenarios
A scenario is one way a provider really delivers: Once, Twice, Shuffled, Late, Retry after error, Tampered, Unsigned, Burst and Slow budget. Once always runs first; it is the setup check. A scenario that doesn’t apply to a provider is markedn/a with the reason, for example Late for GitHub, which signs no timestamp. See Scenarios.
Findings
A finding is a rule the run proved broken, with a severity:Packs
A pack is versioned data about one provider: how to detect it, its signing scheme and timestamp tolerance, its response-time budget, its duplicate and retry headers, which fields Tampered changes, how events group, and the text and citations of its findings. The judge reads packs only. Webhook Trap 2.0 ships packs for Stripe, GitHub, Shopify and Standard Webhooks, all at version 1.0.0, embedded in the agent.The server runner
The engine also has a server runner (webhooktrap serve-run), which runs scenarios from the server against a public URL without an agent. It ships in the self-host Compose file. The app does not start server runs in 2.0: every run goes through a paired agent.