Skip to main content
webhooktrap test runs the same plan, delivery and judge steps as a run started from the browser, but from fixture files in your repository. It needs no server, no account and no pairing; the only network traffic is to your handler. It exits with a code your CI can act on.

What you need in the repository

  • webhooktrap.yml declares the target, the provider, the secret’s variable name, and optionally a probe and a reset. See Configuration.
  • Fixtures are JSON files with the provider, the event type, the headers and the exact body. With provider: stripe and no fixtures: list, test reads every file under webhooktrap/fixtures/stripe/. See Fixture files.
Fixtures carry no signature: the agent re-signs every delivery at send time with the secret from the environment. In CI, set that variable to the same test secret your handler verifies with.

Run it locally first

The first run asks you to confirm the side-effect warning for the target, and the probe and reset commands if there are any. The answers are remembered in .webhooktrap/state.json. In CI, where nobody can answer, pass --yes. This is the output of a real run against a handler that checks the timestamp but only logs a bad signature, and doesn’t record event ids (--ascii, shortened):
The last line is the exit code and why.

Exit codes

--fail-on takes critical, high, medium or never. Info findings never fail a run. See Findings and exit codes.

GitHub Actions

Start your handler in the job, wait until it answers, then run webhooktrap test. This example uses a Node app; adapt the start and reset commands to yours.
.github/workflows/webhooks.yml
Don’t run webhooktrap test with real secrets on pull_request_target: a pull request from a fork would run your cmd: probes and reset with access to them. In a pull_request_target job, webhooktrap test refuses cmd: probes and reset unless you pass --allow-untrusted-config; pass it only for trusted code.

Re-check a run document

Every run writes a run document, by default to .webhooktrap/runs/<run id>.json (--out changes the path). It holds the plan and every observation, so the verdict can be recomputed:
rejudge exits 0 when the verdict is identical, 1 when it differs, and 3 when the file isn’t a local run document.

Useful flags

The full list is in the CLI reference.