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.ymldeclares 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: stripeand nofixtures:list,testreads every file underwebhooktrap/fixtures/stripe/. See Fixture files.
Run it locally first
.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):
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 runwebhooktrap test. This example uses a Node app; adapt the start and reset commands to yours.
.github/workflows/webhooks.yml
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.