Skip to main content

Test the webhooks your app sends, on your machine

When your app is the one that sends webhooks, set the subscriber URL to http://http-dump@127.0.0.1:8000/webhooks/orders. Every webhook your app fires then lands in Buggregator: method, URL, all headers including the signature header, and the body. Each one comes with a cURL command, so you can send it again to a receiver you are building.

Steps

1. Start Buggregator

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/buggregator/server:latest

2. Use Buggregator as the subscriber URL

Register this URL wherever your app stores webhook endpoints: a test subscriber, a seed, a config value. http-dump as the user name marks the request for Buggregator. The path is yours to choose. In Docker Compose, replace 127.0.0.1 with the Buggregator service name, for example buggregator.

text
http://http-dump@127.0.0.1:8000/webhooks/orders

If your HTTP client drops the user name from URLs, send the header X-Buggregator-Event: http-dump instead.

3. Fire one and read it

Trigger the event in your app, for example create an order. Open http://127.0.0.1:8000. The request shows its method, full URI, query parameters, headers, cookies and body. Check the event name, the timestamp header and the signature header your app adds.

4. Check the signature

Copy the raw body and recompute the signature the way your receivers will. For an HMAC-SHA256 hex signature:

bash
printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"

The result must equal the value in your signature header.

5. Send it again

Every captured request has a cURL command with a copy button. Change the URL in it to your receiver's address and run it: the same headers and body arrive there.

6. Test your retries

Point the subscriber URL at the mock server and make a rule that answers 500. Your app gets the error, and each retry shows up as a new request with its time.

bash
curl -X POST http://127.0.0.1:8000/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{"method": "POST", "path": "/webhooks/orders", "status": 500}'
# then use http://127.0.0.1:8000/mock/webhooks/orders as the subscriber URL

Why it works

Buggregator stores any request marked with http-dump, by user name, Basic Auth or header, and answers it with 200. So your app sees a successful delivery while you read exactly what it sent. Nothing leaves your machine, and the webhook never reaches a real customer endpoint.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you