Firing test events

fire builds an event, signs it with your local secret, POSTs it to http://localhost:3000/api/webhooks/<provider> (change with --url), and interprets the response the way the sending provider would. Each provider ships a few realistic fixtures; --list shows them.

Aim events at your own data

Fixtures carry fake ids, which is fine for testing the plumbing but useless for business logic: a handler that looks up the paying customer finds nobody. --set overrides any payload field by dot path and can be repeated, so you point the event at a row in your own dev database. Values parse as JSON when possible (numbers, booleans, objects), otherwise they are strings, and missing intermediate objects are created.

Run the first command and check your database: that user's plan flipped. The second one exercises the downgrade path for the same user, an event you cannot trigger on demand from any dashboard.

Your own payloads

--body <file> sends a file as the payload instead of a fixture, and --set composes with it. Payloads captured by the dev command make good templates: copy one, edit what you need, fire it. --id and --type set the event id and type wherever the provider carries them, headers for GitHub, payload fields for the rest.

Retries and duplicates

Providers deliver at least once, which in practice means sometimes twice. Firing the same id twice exercises your route's dedup: the second run prints 200 duplicate, acknowledged without running the handler.

Reading the output

200 handler ran          signature verified, handler completed
200 duplicate            already processed, handler not run
401 rejected: <reason>   signature check failed; the CLI also prints
                         where the secret it signed with came from
500 failed               your handler threw; the provider would retry

The 401 case is the classic misconfigured-secret hunt reduced to one command: compare the route's rejection reason with the printed secret source, and remember the dev server reads env files only at startup. Exit codes are 0 for any 2xx and 1 otherwise, so fire also works in scripts.

Custom schemes

npx next-webhooks fire hmac --header x-signature --prefix sha256=
npx next-webhooks fire token --header x-webhook-token