Skip to main content
A webhook testing inbox is a URL that stores every HTTP request sent to it. Point your system’s outbound webhooks at it to assert what you send, or point a provider at it to see its real payload before you write a handler.
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 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:

Create an inbox

REST wraps the inbox in data. The CLI with -o json prints the bare object:
Give 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 is https://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 with pathPrefix when you wait.
  • Every reply carries X-Event-Id and X-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 gets 200 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 default 200, 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.