> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webhooktrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Projects, captures, guest sessions, the agent, runs, scenarios, findings, packs and the server runner.

## 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**.

![New project form with the project name brindle-app.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/project-new.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=7fa0ef1772614f7e70e929fe0223aeb0)

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 as `Authorization` and `Cookie` are replaced before storage. See [Capture endpoint](https://docs.webhooktrap.dev/reference/capture-endpoint.md).

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 list with a group header sub\_1QH3… Subscription, Stripe, 3 deliveries, framed.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/captures-stream-group.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=b880b6082640d43df68242256d3f614f)

Arrivals: deliveries grouped by the subscription they belong to.

The delivery page shows the request facts and the raw body. The signature stays **Not checked** in the app: checking it needs your signing secret, which only the agent holds.

![Delivery detail for invoice.paid with signature Not checked and the request facts.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/delivery-detail.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=0621a0d56084a7ff28fe76b0a733e4f5)

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](https://app.webhooktrap.dev/r/example). It is a random token in a cookie and holds one project.

![Guest session · expires in 23 h 59 m · 3/100 deliveries · 0/10 runs · Sign in to keep.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/guest-session-bar.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=c68db94bf7b3c9d9b4b0cabc1b9c5eca)

The guest session bar: time left, deliveries and runs used.

A guest session lasts 24 hours and holds up to 100 deliveries and 10 runs. When it ends, it is deleted with everything in it. Signing in from the session moves its project into your account.

## The agent

The **agent** is the `webhooktrap` 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 page listing maya-mbp, connected, version 1.0.0, linux.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/agents-list.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=92083ccb07394082631b993c39b9883c)

Agents paired with your account.

The same binary runs in CI with `webhooktrap test`, which needs no server and no pairing. See [CLI](https://docs.webhooktrap.dev/reference/cli.md).

## 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 carries `Webhooktrap-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:

| Level | Needs | Checks |
| - | - | - |
| Level 1, transport | nothing | status codes, latency against the provider's budget, whether forged or stale deliveries are accepted |
| Level 2, state | a `probe` in `webhooktrap.yml` | whether your database state after each delivery is the state one clean delivery leaves |

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](https://docs.webhooktrap.dev/reference/findings.md).

![Runs page listing Run #1 with 2 findings, run by maya-mbp from the web app.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/runs-list.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=c4cf8e62c6343b08dac5a6dc67be5564)

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 marked `n/a` with the reason, for example Late for GitHub, which signs no timestamp. See [Scenarios](https://docs.webhooktrap.dev/reference/scenarios.md).

## Findings

A **finding** is a rule the run proved broken, with a severity:

| Severity | Meaning |
| - | - |
| Critical | Forged input had an effect: anyone who can reach the URL can make the handler act on content the provider never sent. |
| High | A real provider behaviour corrupts state or loses the delivery. |
| Medium | Operational risk: the provider will see failures and retry, alert or disable the endpoint. |
| Info | Something the run couldn't check, or a suggestion. Never counted. |

## 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.

| Pack | Budget | Signature header | Signed timestamp |
| - | - | - | - |
| Stripe | 10 s (Webhook Trap default) | `Stripe-Signature` | yes, 300 s tolerance |
| GitHub | 10 s (GitHub limit) | `X-Hub-Signature-256` | no |
| Shopify | 5 s (Shopify limit) | `X-Shopify-Hmac-Sha256` | no |
| Standard Webhooks | 10 s (Webhook Trap default) | `webhook-signature` | yes, 300 s tolerance |

## 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](https://docs.webhooktrap.dev/guides/self-hosting.md). The app does not start server runs in 2.0: every run goes through a paired agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.