Skip to main content
Trigger the code that sends the webhook, then wait. Omit receivedAfter and the server looks back 60 seconds. The API holds the request until a matching event is stored and returns it, or answers 408 when the timeout passes.

Setup

Export an API key. When the organization has one workspace, leave the workspace unset: the API uses that workspace, and the CLI and SDKs omit x-phelm-workspace-id. When it has more than one, export the workspace ID as well.
The CLI and Python SDK read DEVHELM_API_TOKEN. The TypeScript SDK takes the key in its constructor and reads DEVHELM_WORKSPACE_ID when it is set. With curl, send the workspace header only when you set the variable:
Install the SDK and a test runner: npm install --save-dev @devhelm/sdk vitest or pip install devhelm pytest. The TypeScript SDK is ESM only.

Complete example

The test file creates an inbox, triggers a send, waits, asserts, and deletes the inbox. Replace placeOrder / place_order with the call that makes your system send its webhook to the inbox URL.
Header names are stored lowercased, so read content-type, not Content-Type. event.json() parses event.body, which wait returns in full.

How wait matches

Omit receivedAfter for the 60 second lookback

REST, the CLI, and both SDKs omit receivedAfter the same way: the server matches events from the last 60 seconds and returns the oldest. A fresh inbox, or a per-test path, keeps an earlier run out of that window. Pass receivedAfter when you need a cursor, such as the previous event’s receivedAt plus 1 ms. The complete example shows the SDK form. From the CLI or curl:
The CLI prints the bare event; curl returns {"event": {...}}, or on timeout:

Set the runner timeout above the wait timeout

A runner kills a test that passes its own timeout, whatever the wait is doing. Give each waiting test more than its timeoutMs, plus time for the trigger. A longer runner timeout does not extend the wait: the server stops at timeoutMs, capped at 120 seconds. The SDKs set their HTTP timeout to timeoutMs plus 10 seconds, so the client does not cut off a wait the server still holds. Playwright tests call the same SDK wait. There is no separate Playwright package.

Wait for several webhooks

To read the second or Nth event, wait again with receivedAfter set to the previous event’s receivedAt plus 1 ms. Do not list events after a wait to find the later ones: a list can miss events that are not stored yet.
A second event received less than 1 ms after the first is skipped by the step. Send such events to different paths and wait on each. To assert exactly N webhooks, wait for N, then add a negative assertion after the Nth.

Assert that no webhook was sent

A wait that ends in 408 proves nothing matched during its timeout. Both SDKs raise a generic DevhelmApiError with status 408 and code "WAIT_TIMEOUT"; there is no timeout subclass, so check code.
The timeout must cover your sender’s latency plus the storage lag: events become visible about 1 to 5 seconds after the sender’s request. Start at 10 seconds and raise it for queued senders. A passing negative assertion always takes the full timeoutMs and spends one call from the wait budget.

Parallel tests on one inbox

Inboxes are capped per organization (3 on the Free testing plan, 10 on Developer), so use one inbox per CI job and one path per test. The sender posts to <httpUrl>/<run-id>/<test-id>/... and the test waits on that pathPrefix, so tests never match each other’s events.
Point your system’s webhook URL at the test’s lane URL. With pytest-xdist, each worker runs the session fixture and creates its own inbox, so size -n to your inbox quota. The CI guide covers secrets, teardown, and fork pull requests.

The wait budget is shared

All wait calls in an organization share 40 per minute, across webhook and email waits and every workspace. A call counts once, however long it waits. Four parallel jobs making 15 waits each within one minute get 429 after the 40th call. Over the limit, the API returns 429 RATE_LIMITED with Retry-After, and the SDKs raise DevhelmRateLimitError with retryAfter (TypeScript) or retry_after (Python) in seconds. Neither SDK retries on its own. Retry after that many seconds with the same since; wait does not consume, so nothing is lost.

Troubleshooting

  • receivedAfter was set after the trigger, so the request is older than the cursor. Omit it on a fresh inbox.
  • The sender was refused. 404 means a wrong, disabled, or deleted inbox; 413, 429, and 403 mean nothing was stored.
  • The filters do not match. pathPrefix is case-sensitive and starts with /. Check stored paths with devhelm inboxes events list <inbox-id> -o json.
  • It was a browser preflight. Wait skips OPTIONS unless you pass method: "OPTIONS".
  • The CI clock runs ahead, or the timeout is shorter than your sender’s queue.
Wait returns the oldest match since receivedAfter. Pass a since taken right before the trigger, and give each test its own path prefix.
The runner’s limit is shorter than timeoutMs. Vitest and Jest stop a test at 5 seconds by default.
The sender gets X-Event-Id before the event is stored, so a get right after the send can 404 for about a second. Wait for the event instead.

Next steps

How inboxes capture requests

What an event stores and how to read it.

Wait for an email in a test

The same wait semantics for testing mailboxes.

Simulate a failing receiver

Return 5xx and delays, then assert on your retries.

Verify webhook signatures

Check the HMAC over the raw body bytes.

Testing in CI

One inbox per job, secrets, teardown, and 429 backoff.

Limits, quotas, and errors

Every limit and error code in one table.