Skip to main content
Set an inbox’s mock reply to an error status, extra headers, or a delay, then watch what your sender does. The inbox stores every request before it replies, so each attempt is captured whatever the reply says.
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:

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

To change an existing inbox, PATCH 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, capture since, 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

Set delayMs above your sender’s request timeout. The request is stored first, so the attempt is captured even though your sender gives up.
The maximum delay is 30 seconds, so a sender timeout above 30 seconds cannot be tested this way. Lower the sender’s timeout in the test environment instead. Combine a delay with a status to model a slow failure, such as {"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

A PATCH that includes headers, or devhelm inboxes update --response-header, replaces the whole map. Send every header you want to keep in the same request.
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 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.