webhooktrap.yml sits at the root of your project. webhooktrap test and webhooktrap agent read it from the current directory; --config points at another file.
webhooktrap.yml
webhooktrap test exits 3 and sends nothing.
Keys
Where deliveries go: an
http:// or https:// URL with no credentials. A host that resolves only to loopback (127.0.0.0/8, ::1, localhost, *.localhost) is allowed. Any other host must be listed in targets. Provider domains, metadata endpoints and hosts that resolve to both loopback and other addresses are always refused. The agent resolves the host once per run and uses those addresses for every delivery.The pack to use:
stripe, github, shopify or standard_webhooks. Without fixtures, test reads webhooktrap/fixtures/<provider>/. Without provider, the provider of the first fixture is used.The environment variable that holds the signing secret, written
env:NAME (uppercase letters, digits and _). A value is never accepted here. Default: the pack’s variable (STRIPE_WEBHOOK_SECRET, GITHUB_WEBHOOK_SECRET, SHOPIFY_API_SECRET, WEBHOOK_SECRET).Fixture files for
webhooktrap test, in place of the provider’s fixture directory. See Fixture files.Scenarios for
webhooktrap test, by machine name: once, twice, shuffled, late, retry, tampered, unsigned, burst, slow_budget. --scenarios overrides it. Default: all.Response-time budget, in place of the pack’s. Written
5000 or 5000ms. A value above a budget the provider documents (GitHub 10 000 ms, Shopify 5 000 ms) is refused, because it would hide a failure the provider documents. A value above a Webhook Trap default (Stripe, Standard Webhooks) is allowed.The framework of your handler, for fix snippets. By default it is detected from the response headers (
X-Powered-By, a laravel_session cookie).Non-loopback hosts the agent may send to, as exact
host:port entries. A run to a listed host prints a warning every time. The server can’t add to this list.Commands or URLs that read your state after each delivery. Each entry has:
as: the probe’s name, 1 to 48 characters froma-z,0-9,_and., unique in the file;- exactly one of
cmd:(a shell command) orurl:(a URL fetched through the same target rules).sql:is reserved: this build refuses it and suggests acmd:withpsql; covers(optional): the object types this probe reads, such asinvoiceorsubscription. A run reports object types that no probe covers;show(optional): accepted, but agent 1.0.0 doesn’t use it; readings are always sent as display forms.
probe_unstable). Avoid time-based values such as updated_at or now().Default
0: the probe is read once, right after the response. With settle: 2s, it is read every 250 ms until its value has been unchanged for 2 s, for at most 2 s + 5 s; a value that never settles makes that judgement Inconclusive. Use it when your handler writes from a background job.Runs before every scenario, Once included, so each scenario starts from the same state. Timeout 60 s. A failing reset stops the run. Without a reset, the judgements that compare against the state after Once are Inconclusive and the run gets the Info finding No reset between scenarios.
Confirmation of commands
cmd: probes and reset run on your machine, so they are shown and confirmed once per version of the file (by its SHA-256). webhooktrap test remembers the answer in .webhooktrap/state.json; in CI, pass --yes. The agent asks in its terminal.
Probe and reset commands run without the signing secret, or any secret variable a pack names, in their environment.
Probe templates
A probe can name an object of the selected events:{{invoice.id}} is the id of the first invoice among them.
- A value is used only if it is a plain id: 1 to 128 characters from
A-Z,a-z,0-9,_and-, matching the pack’s id pattern when it has one. Anything else is refused:webhooktrap testexits3, and the agent aborts the run. - A
cmd:probe never gets the value in its command text. The value is passed as the environment variableWT_<TYPE>_ID({{invoice.id}}→WT_INVOICE_ID), and the template becomes a reference to it, quoted for where it sits. You can write the reference yourself:'$WT_INVOICE_ID'. - On Windows the reference is
!WT_INVOICE_ID!and commands run withcmd.exe /D /V:ON /S /C. Don’t write%WT_INVOICE_ID%. Escape a literal!as^!. - A
url:probe gets the value query-escaped.
What the server sees
The agent sends the server the target’s scheme, host and port, the secret’s variable name, and a hash of the probe configuration. Probe readings leave your machine only as display forms: counts up to 9 999 as numbers, other values as short codes such as#a1f3c0, which only show whether a value changed. Commands, raw values and probe output stay on your machine.