The CLI

The package ships a command line tool for developing and debugging webhook endpoints. It installs with next-webhooks, so it is already in your project. Node 20+, no extra dependencies, and nothing from the CLI is imported by the code your routes run.

Why it exists

Testing a webhook endpoint has two separate problems. The first is that the internet cannot reach your laptop: providers deliver to a public URL and your dev server is localhost. Tunnels like ngrok and cloudflared solve that, and the CLI does not try to replace them.

The second is that you cannot summon a delivery on demand, and that is the one the CLI solves. Without it, running your handler means making the provider send a real event: a test purchase in a dashboard, a push to a repo, a message in a channel. That is slow when the event is easy to trigger, and some of the most important events are nearly impossible to trigger at will. invoice.payment_failed needs a card that declines at the right moment. charge.dispute.created needs an actual dispute. And curl cannot shortcut any of this, because your route correctly rejects unsigned requests.

The whole tool rests on one insight: the only thing standing between curl and your route is the signature. The CLI computes valid signatures with your local secret. Everything else, the payload included, is plain JSON that you control.

Scope

What it does:

• Scaffolds verified routes and checks the whole setup (init, doctor)
• Signs and sends events for stripe, github, svix (Clerk, Resend, Polar), slack, paddle, shopify, lemonsqueezy, and vercel, plus generic hmac and token schemes
• Ships realistic fixture payloads per provider, so the first fire needs zero setup
• Records real deliveries, headers plus the exact raw body, to a JSONL file
• Re-signs recorded deliveries so they verify against your local secret

What it deliberately does not do:

• No tunnel; use ngrok or cloudflared, the dev command composes with them
• No calls to provider APIs, no accounts, everything stays local
• No production role; it is a development tool only

Where secrets come from

Commands resolve the signing secret in this order: the --secret flag, then real environment variables, then the env files Next.js loads from your project (.env, .env.development, .env.local, .env.development.local, later files win). Error messages say exactly which variables and files were searched, and successful sends print where the secret came from.