What Is Webhook Testing?

Webhook testing proves that your system sent the right HTTP request to a receiver: the right event, body, headers, and signature, at the right moment. The test triggers the action, captures what was sent, and asserts on it.

How it works

A capture endpoint is a URL that accepts any request and stores it. Your test points the code under test at that URL, makes it send, then reads back what arrived:

Configure the sender to use the capture URL instead of the real receiver.
Trigger the action that should send a webhook: place an order, change a status, run a job.
Read the captured request: method, path, query, headers, and raw body.
Assert on the parts that matter: the event type, the payload, the signature header.

The capture endpoint can also play the receiver’s part in the reply. Returning a 500 or a slow response is how you test the sender’s retries and timeouts.

Three things called “webhook”

The word covers traffic in both directions. In the DevHelm docs:

	Who sends	Who receives	What it proves
Webhook inbox (capture)	Your code	A DevHelm inbox	Your system sends the right requests
Uptime check	DevHelm probes	Your endpoint	Your endpoint is up and answers correctly
Alert webhook	DevHelm	Your URL	You hear about incidents in your own tools

An inbox is a testing tool. An HTTP monitor checks your receiver from outside on a schedule. An alert webhook is DevHelm sending events out.

Getting the request into the test

	How it works	Good for	Weak at
Poll	List captured requests in a loop with a sleep between tries	Ad hoc inspection	Sleeps make tests slow when long and flaky when short
Wait	One call blocks until a matching request is stored, or fails with a timeout	Assertions in CI	Needs a start time, below
Tunnel	Forward the request to a process on your machine	Running your own receiver code during development	Needs a live process; leaves no stored record to assert on

DevHelm inboxes use a server-side wait. It returns the oldest stored request that matches, as soon as it exists, or 408 WAIT_TIMEOUT when the time runs out. DevHelm does not forward or replay requests to another URL.

Record the start time first

A wait has to know which requests count. It matches requests received at or after a timestamp you pass. Take that timestamp before the trigger:

const since = new Date().toISOString();
await placeOrder();
const event = await inbox.wait({ receivedAfter: since, timeoutMs: 30_000 });

Taken after the trigger, a fast sender has already delivered, the request falls outside the window, and the wait times out. The DevHelm CLI and SDKs default this timestamp to the moment you call wait, so pass it explicitly. Waiting does not consume anything. The same call returns the same request again, which keeps retries of a test step safe.

Proving nothing was sent

“No webhook is sent for a failed payment” is a wait that is expected to time out. Its timeout has to cover the sender’s normal latency plus the few seconds the inbox takes to store a request. Too short, and the test passes before a late request lands.

One inbox per test

A shared capture URL is the most common source of wrong matches: two tests, or two CI jobs, send to the same inbox, and one reads the other’s request. Isolate by test:

One inbox per test is the simplest. Create it at the start, delete it at the end.
One inbox per CI job, one path per test fits a plan’s inbox cap. The inbox accepts any path below its token, so each test sends to /<run-id>/<test-id> and waits with that path as a prefix.

Inbox slots are counted per organization, and all waits in an organization share one rate limit. Testing in CI shows a layout that fits both.

Signatures

Most providers sign each webhook so the receiver can tell it is genuine. Stripe sends Stripe-Signature, GitHub sends X-Hub-Signature-256, and the Standard Webhooks spec uses webhook-signature. Each is an HMAC over the exact bytes of the body. That makes signature tests fragile in one specific way: any step that parses and re-serializes the body changes whitespace or key order, and the HMAC no longer matches. Verify against the raw bytes, never against a parsed or decoded copy. A DevHelm inbox stores the raw body byte for byte, with its SHA-256, and keeps every header. Header names arrive lowercased, so look up stripe-signature, not Stripe-Signature. There is no built-in verify call; you run the same check your receiver runs. Verify webhook signatures has the code for each scheme.

Testing failure handling

Receivers fail, and senders are supposed to retry. To test that, the capture endpoint has to fail on purpose: return a 500, a 429, or a slow reply, then let the sender retry and check the attempts it made. A DevHelm inbox has a configurable reply (status, body, headers, and a delay of up to 30 seconds) for this. See Simulate a failing receiver.

Monitoring

Incidents

AI & Automation

Testing

What Is Webhook Testing?

How it works

Three things called “webhook”

Getting the request into the test

Record the start time first

Proving nothing was sent

One inbox per test

Signatures

Testing failure handling

DevHelm webhook inboxes

Your first webhook inbox

Webhook inboxes

​How it works

​Three things called “webhook”

​Getting the request into the test

​Record the start time first

​Proving nothing was sent

​One inbox per test

​Signatures

​Testing failure handling

​DevHelm webhook inboxes

Your first webhook inbox

Webhook inboxes

How it works

Three things called “webhook”

Getting the request into the test

Record the start time first

Proving nothing was sent

One inbox per test

Signatures

Testing failure handling

DevHelm webhook inboxes