Setup
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 The CLI and Python SDK read
x-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:The mock reply
Every request to the inbox gets the same reply, whatever its path or method.X-Event-Id and X-Inbox-Id are always added and replace same-named configured headers. With cors on (the default), every reply also carries Access-Control-Allow-Origin: *. An invalid value returns 400 with a field-specific code: INBOUND_HTTP_RESPONSE_STATUS_INVALID, INBOUND_HTTP_RESPONSE_DELAY_INVALID, INBOUND_HTTP_RESPONSE_BODY_TOO_LARGE, INBOUND_HTTP_RESPONSE_BODY_INVALID, INBOUND_HTTP_RESPONSE_CONTENT_TYPE_INVALID, or INBOUND_HTTP_RESPONSE_HEADERS_INVALID.
The reply applies to the whole inbox, so a failing reply breaks any other test sharing it. Give each failure test its own inbox and delete it afterwards.
Set a failing reply
httpResponse. Fields you leave out keep their values, except headers: sending it replaces the whole map, and "headers": {} clears it. The change applies from the next request.
devhelm inboxes update cannot change the status, body, content type, or delay. Its only reply flag is --response-header, which also replaces every configured header.
Reply headers
Up to 32 headers. Names must match[A-Za-z][A-Za-z0-9-]{0,63}, and values must be printable ASCII up to 1,024 characters. These 14 names are rejected, case-insensitively, with 400 INBOUND_HTTP_RESPONSE_HEADERS_INVALID:
Set the content type with
contentType, not a header. Retry-After, X-RateLimit-Reset, and Location (with a 3xx status) are allowed.
Fail, then succeed
The inbox has no “fail N times, then succeed” setting. The test changes the reply between attempts: create a failing inbox, capturesince, trigger the send, wait for the first attempt, PATCH the reply to 200, then wait for the retry with receivedAfter set to the first attempt’s receivedAt plus 1 ms.
deliverWebhook / deliver_webhook stands for your sender. It must return before its retries finish, as a queued job does.
The PATCH has to land before the retry. The first wait returns about 1 to 5 seconds after the attempt, because events are stored a moment after they arrive, so set your sender’s first retry delay to 10 seconds or more in the test environment. If it retries faster, assert “at least one 503, then a success” instead of an exact count.
Each attempt counts toward the monthly event quota, and each wait toward the 40 waits per minute your organization shares. See Wait for a webhook in a test for the full wait semantics.
Simulate a timeout
SetdelayMs above your sender’s request timeout. The request is stored first, so the attempt is captured even though your sender gives up.
{"status": 504, "delayMs": 25000}.
Browser senders
Test failure statuses from a server-side sender. A browser’s CORS preflight (OPTIONS) gets the mock status, so with a 4xx or 5xx reply the browser fails the preflight and never sends the real request. The preflight itself is still captured.
Troubleshooting
The retry also got the failure
The retry also got the failure
The retry arrived before your PATCH. Lengthen the sender’s first retry delay in the test environment, or assert “at least one failure, then a success”.
The third wait returned an event instead of 408
The third wait returned an event instead of 408
The sender kept retrying after the 200, or another test sent to the same inbox and path. Check the event’s
path and headers, and use a dedicated inbox.Next steps
Wait for a webhook in a test
Full wait semantics, the Nth event, and negative assertions.
How inboxes capture requests
What an inbox stores, and when a sender is refused.
Testing in CI
One inbox per job, secrets, cleanup, and the shared wait budget.
Limits, quotas, and errors
Quotas, rate limits, and every error code.
Wait for an email in a test
The same wait semantics for testing mailboxes.
Verify webhook signatures
Check the HMAC on each captured attempt.