# How to Test Webhooks Locally (Without Deploying)

> Test webhooks on localhost by giving the provider a public HTTPS URL that forwards to your machine. Then inspect, replay and send signed events.

- Published: 2026-10-30
- Page: https://www.otterkit.com/blog/test-webhooks-locally

# How to Test Webhooks Locally (Without Deploying)

To test webhooks locally, give the provider a public HTTPS URL that passes requests through to the server on your machine. Then capture every request so you can read it, fix your handler and replay it without waiting for the provider to send it again.

The steps below cover the whole loop:

- getting a URL
- sending events to localhost
- inspecting payloads
- replaying requests
- checking signatures
- the problems that catch most people

## Why webhooks are hard to test on localhost

A webhook is an HTTP request that another service sends to you. Your browser can open `http://localhost:3000` because it runs on the same machine as your server. Stripe or GitHub can't reach that address, because `localhost` only points at your own machine and isn't reachable from the internet.

That leaves a few common workarounds, and each has a cost:

- **Deploy every change to a staging server.** This works, but every small fix means a deploy before you can test again.
- **Copy a payload from the provider's dashboard and `curl` it yourself.** This is quick, but you lose the real headers. Your signature check will fail, or you'll switch it off and forget to turn it back on.
- **Use a provider's own CLI.** Some providers ship one. It only covers that provider, though, and many integrations involve more than one sender.

What you want is a public address that catches the real request, keeps a copy, and either answers for you or forwards the request to your port.

## Get a public webhook URL in seconds (no account)

The quickest way to see what a provider actually sends is a throwaway capture URL. OtterKit's [try page](https://www.otterkit.com/try) gives you a live webhook URL in the browser with no account. Requests show up as they arrive.

Paste it into a provider's webhook settings, or send it something by hand:

```bash
curl -X POST https://try-….otterkit.app/orders \
  -H "content-type: application/json" \
  -d '{"order_id":"ord_42","total":128}'
```

Try URLs are public, so don't send real secrets or customer data to them.

To keep going with the same URL, log in and claim it from your terminal:

```bash
npx otterkit login
npx otterkit webhook --claim <code>
```

Once you're logged in, you can also start a new endpoint directly with `npx otterkit webhook`.

## Forward incoming events to your local server

You can get a provider's requests to your local handler in two ways. Which one fits depends on who should answer the provider.

**Option 1: a webhook endpoint that also sends a copy to localhost.** OtterKit's servers answer the provider, and `--deliver` sends a copy of each capture to your machine:

```bash
npx otterkit webhook --deliver 3000
# or a specific route
npx otterkit webhook --deliver http://localhost:8787/stripe-events
```

If your app crashes halfway through debugging, the sender still gets its 200 and the request is still in the log. You only miss the copy. This suits early development, when your handler is likely to throw.

For a script instead of a server, `--deliver-exec` runs a shell command for each capture. The body arrives on stdin, and details such as `OTTERKIT_PATH` and `OTTERKIT_VERIFIED` arrive in environment variables ([Local Delivery docs](https://www.otterkit.com/docs/cli-deliver)).

**Option 2: a tunnel straight to your port.** Your own server answers the provider, so you're testing the real response:

```bash
npx otterkit tunnel 3000 --subdomain stripe-dev
# paste https://stripe-dev.otterkit.app/webhook into the provider's dashboard
```

`--subdomain` reserves the name to your account, so the URL stays the same across restarts and you don't have to change the provider's settings each time. Tunnels capture traffic to a local log by default. `--auth user:pass` puts a password on the URL that's checked on your machine ([Tunnels docs](https://www.otterkit.com/docs/tunnels)).

The difference matters when your laptop is closed. Webhook endpoints keep answering and hold requests until you reconnect. Tunnels need your machine, so they pause.

## Inspect headers and payloads as they arrive

Reading the exact request answers most webhook bugs: which event type arrived, which fields are set and what the signature header looks like.

CLI webhook endpoints write every request to `~/.otterkit/requests/<subdomain>.jsonl`, and so do tunnels unless you pass `--no-log`. Captures from CLI webhook endpoints stay on your machine.

```bash
npx otterkit inspect hook-a1b2c3d4                       # browse the log
npx otterkit inspect hook-a1b2c3d4 --follow              # live-tail
npx otterkit inspect hook-a1b2c3d4 --follow --status 5xx # only failures
```

The `--status 5xx` filter shows only the requests your handler failed on. `inspect` can also filter and export captures in other ways, and the [Inspect docs](https://www.otterkit.com/docs/cli-inspect) list every option.

## Replay a request after fixing your handler

Without a replay tool, the slowest part of webhook work is triggering the event again: another test checkout, another push or another form submission.

`otterkit replay` resends a captured request to your local server, and replaying is free. You can also edit the request before sending it, such as its method, path, headers or JSON body fields, which helps when testing edge cases. The [Replay docs](https://www.otterkit.com/docs/cli-replay) cover the options.

Keep in mind that changing the body of a signed request means it no longer matches the original signature. Your handler's signature check will reject it unless the edited body is signed again.

## Verifying signatures and sending test events

Most providers sign each webhook so you can confirm it really came from them. Signature failures are some of the most confusing bugs, because the payload looks right but your handler rejects it.

**Check signatures when requests arrive.** Give the endpoint your signing secret:

```bash
npx otterkit webhook --verify stripe:whsec_abc123 --deliver 3000
```

Each capture is then marked valid, invalid or missing, and your local server receives the result as an `X-OtterKit-Verified` header. A request with a bad signature still gets answered; it's just marked.

Sixteen providers are supported, including Stripe, GitHub, Shopify, Slack, Svix-based senders, Paddle, Linear and Twilio ([Webhooks docs](https://www.otterkit.com/docs/webhooks)).

**Work out whether the bug is in your check or in the payload.** OtterKit can check your saved captures' signatures against a secret, locally.

- If captures fail with the correct secret, the payload was altered on the way, or your code isn't verifying the raw bytes.
- If they all pass, the bug is in your handler.

**Send signed events without a provider account:**

```bash
npx otterkit send stripe:invoice.paid
```

This fires a correctly signed event at your handler, with no dashboard and no test account. Built-in events cover Stripe (for example `invoice.paid` and `customer.subscription.deleted`), GitHub, Shopify and Slack ([Send & Verify docs](https://www.otterkit.com/docs/cli-send)).

## Common pitfalls: timeouts, retries and HTTPS

**Parsing the body before checking the signature.** Many frameworks parse JSON before your code runs. The signature covers the raw bytes, so checking it against a re-serialised object fails even when the request is genuine. Read the raw body on your webhook route.

**Slow responses.** Providers expect a fast 2xx and may treat a slow reply as a failure. Reply quickly and do heavy work in the background. To see how a sender reacts to a slow reply, add a delay of up to 10 seconds:

```bash
npx otterkit webhook --respond-delay 2000
```

**Not testing retries.** Most providers retry failed deliveries, which means your handler can receive the same event more than once. Make handlers idempotent, for example by storing event IDs you've already processed. To make one path fail on purpose and watch the retries arrive:

```bash
npx otterkit webhook --respond-match path=/flaky --respond 500
```

**Plain HTTP.** Many providers won't send to a URL that isn't HTTPS. Both the tunnel and webhook URLs above are HTTPS.

**A URL that changes every run.** If your tunnel gets a new random address each time, you'll keep editing the provider's dashboard. Reserve a name with `--subdomain`.

**Verification challenges.** Some senders, like Slack, send a challenge request before they deliver real events, and expect it echoed back. A response rule can handle it:

```bash
npx otterkit webhook --respond-match type=url_verification \
  --respond 200 --respond-body '{"challenge": "{{challenge}}"}'
```

## FAQ

**Can I test webhooks locally without exposing my machine?**
Yes. Use a webhook endpoint with `--deliver` instead of a tunnel. The public URL is answered by OtterKit's servers, and only a copy reaches your machine. You can also skip the internet entirely and use `otterkit send` to fire signed test events at your handler.

**How do I wait for a webhook in CI?**
Start an endpoint in the background with `otterkit webhook --daemon --json` and trigger the event. Then run `otterkit await`, which blocks until the request you expect shows up and then exits 0. That gives you trigger, wait, assert ([Await docs](https://www.otterkit.com/docs/cli-await)).

**Can an AI coding agent run this loop?**
Yes. `otterkit mcp` exposes tools such as `webhook_create`, `request_await`, `request_replay` and `event_send` to Claude Code, Cursor and other MCP clients ([MCP server docs](https://www.otterkit.com/docs/mcp-server)).

**What does it cost?**
The try page needs no account. After that, endpoints cost $0.01 per live hour, capped at $3 per endpoint every 30 days, and new accounts get 10 free credits. Replaying requests and sending signed test events are free. See [pricing](https://www.otterkit.com).
