An inbox receives requests. Webhook alert channels and platform webhooks go the other way: DevHelm sending events to you.
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:
Create an inbox
data. The CLI with -o json prints the bare object:
httpUrl to the sender and use id for every API call. The publicToken in the URL is the secret, and it cannot be rotated: create a new inbox for a new URL. Inboxes count per organization against your testing plan (3 on Free, 10 on Developer), and names need not be unique.
Send it a request
The ingest URL ishttps://api.devhelm.io/api/v1/ingest/<public-token>, plus any path you add. It needs no authentication.
- Any method is accepted, including
OPTIONS,PROPFIND, and custom verbs. - The part after the token is stored as
path(""when there is none). Percent-escapes are kept as sent, and empty segments (//) collapse. Give each test its own path and match it withpathPrefixwhen you wait. - Every reply carries
X-Event-IdandX-Inbox-Id, so a server-side sender can log which event it produced.
What is stored
The raw bytes are stored exactly as received, whatever the content type.
body is only a text view of them, so signature checks must use the raw bytes: see Verify webhook signatures.
The Python SDK does not expose
body_truncated, raw_url, or the inbox’s last_event_at. Use body for text and event.raw() for the bytes.
Events are stored a moment after the reply
The sender gets200 and X-Event-Id before the event is written. Getting that event by ID can return 404 for about a second, and a list can miss events sent a few seconds earlier. In a test, wait instead: it returns once the event is stored.
Mock reply and event limit
Every sender gets the inbox’s configured reply: by default200, an empty text/plain body, and no delay. You can set the status (200–599), body (up to 65,536 bytes), content type, a delay of up to 30 seconds, and up to 32 headers to make your sender retry or time out. See Simulate a failing receiver. With cors on (the default), every reply has Access-Control-Allow-Origin: *, but a regular reply does not expose X-Event-Id to browser JavaScript. Read event IDs from a server-side sender or the API.
An inbox keeps at most maxEvents events (default 10000, range 1–100000). Past that, the oldest event is dropped.
CLI
Find and read events
The raw endpoint returns
{url, expiresAt, filename, contentType, sizeBytes}. Download url within 60 seconds; its bytes match sha256. The SDKs and CLI download it for you.
devhelm inboxes events clear <inbox-id> -y removes every event. To delete one, call inbox.events.delete(eventId) in either SDK or DELETE /api/v1/webhook/inboxes/<inbox-id>/events/<event-id>. The CLI has no single-event delete.
Activity over 24 hours
Activity returns 24 hourly UTC buckets per inbox, oldest first, for up to 100 inboxes per call. Counts include deleted events and the current partial hour.Disable or delete an inbox
What a sender can get back
Anyone with the URL can send. Reading needs workspace access: every member at any role, and every API key for the workspace, can read, download, and delete events, including any
Authorization header a sender included. See Security and data and Limits, quotas, and errors.
Reference: CLI inboxes, TypeScript SDK, Python SDK, and the Webhook Testing API.
Next steps
Wait for a webhook in a test
Block until the matching request arrives, then assert on it.
Simulate a failing receiver
Return 5xx, slow replies, and custom headers to test retries.
Verify webhook signatures
Recompute the HMAC over the raw body bytes.
Your first webhook inbox
Create an inbox, send a request, wait, and assert.
What is webhook testing?
Capture vs tunnel vs uptime check, and why wait beats polling.
Testing in CI
One inbox per job, secrets, cleanup, and the shared wait budget.