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 omitx-phelm-workspace-id. When it has more than one, export the workspace ID as well.
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:
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. ReplaceplaceOrder / place_order with the call that makes your system send its webhook to the inbox URL.
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:
{"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 itstimeoutMs, 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 withreceivedAfter 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.
Assert that no webhook was sent
A wait that ends in408 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.
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.
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 get429 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
Wait returns 408 but the webhook was sent
Wait returns 408 but the webhook was sent
receivedAfterwas set after the trigger, so the request is older than the cursor. Omit it on a fresh inbox.- The sender was refused.
404means a wrong, disabled, or deleted inbox;413,429, and403mean nothing was stored. - The filters do not match.
pathPrefixis case-sensitive and starts with/. Check stored paths withdevhelm inboxes events list <inbox-id> -o json. - It was a browser preflight. Wait skips
OPTIONSunless you passmethod: "OPTIONS". - The CI clock runs ahead, or the timeout is shorter than your sender’s queue.
Wait returns a webhook from an earlier test
Wait returns a webhook from an earlier test
Wait returns the oldest match since
receivedAfter. Pass a since taken right before the trigger, and give each test its own path prefix.The test fails with the runner's timeout, not 408
The test fails with the runner's timeout, not 408
The runner’s limit is shorter than
timeoutMs. Vitest and Jest stop a test at 5 seconds by default.Getting an event by X-Event-Id returns 404
Getting an event by X-Event-Id returns 404
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.