Concepts
Four nouns carry the whole product: an Endpoint captures Requests, its Actions decide what happens to each one, and every action that runs leaves a Delivery with a full attempt history.
Learn these four nouns once and every screen and every API response is predictable.
Endpoint
An endpoint is a capture URL: https://in.webhookvault.net/hook/{id}. Anything HTTP that
reaches it is stored: every method, any content type, binary bodies included (stored base64,
flagged bodyIsBinary). The endpoint answers the sender with the response you configure
(status, headers, body), independent of what happens to the request afterwards.
- An endpoint that is switched off answers
410and stops capturing: visibly off, never half-alive. - A deleted endpoint answers
404, immediately. - An ephemeral endpoint (created with
ttlSeconds) answers404after its expiry and is then swept away with everything it captured. Built for CI runs.
Sub-paths are captured too: senders can call …/hook/{id}/anything/here and the path is stored with
the request.
Captured request
A captured request is the stored record: method, path, query string, headers, body, source IP, size, timing. It lives until your plan's retention window expires it or the per-endpoint storage cap evicts it oldest-first, so the vault always stores the newest arrival and ages out old ones rather than refusing a sender. Deleting one does not remove it: it moves to the recycle bin for 7 days first.
Two honesty flags matter when reading one back:
| Flag | Meaning |
|---|---|
bodyIsBinary | body holds base64 of the original bytes (invalid UTF-8 or NUL content). Decoded back to bytes on forward/replay. |
bodyTruncated | The body exceeded your plan's payload cap. Only its size was recorded; it cannot be replayed, and the API will say so rather than send a placeholder. |
Action
An action is something an endpoint does with each captured request after it has answered the sender. An endpoint holds an ordered list of actions, up to your plan's per-endpoint limit (1 on Free, 3 on Solo, 10 on Pro, 25 on Team). There are three kinds:
| Kind | What it does | Plan |
|---|---|---|
forward | POSTs the capture to a URL you choose. | Every plan |
notify | Sends a short message through one of your alert channels. | Pro and Team |
subrequest | Sends one of your saved requests from the dashboard Library, with fields of the capture filling the slots it declares. | Every plan |
Each action can carry its own condition, written in the same predicate grammar as a transformation, so only matching captures run it. Every action sees the original capture: actions never chain, and one failing never affects another. Actions are managed in the dashboard or through the actions endpoints.
Delivery
When an endpoint has at least one active action, every capture becomes a delivery for each action that runs: a background job that carries out the action, retries on failure with exponential backoff, and parks in a dead-letter state when retries are exhausted. A forward is attempted eight times in all: the first retry waits about 30 seconds after the first failure and each later wait doubles. Every attempt, automatic or manual, is recorded and readable via the attempts endpoint.
The delivery state on a request is always one of:
| State | In the app | Meaning |
|---|---|---|
NotAttempted | n/a | The endpoint had no active action when the request arrived. |
Skipped | skipped | The endpoint has actions, but each has a condition and none matched this request, so nothing was queued. |
Pending | sending | Queued or in flight. |
Succeeded | delivered code | The destination answered 2xx. |
Failed | errored code | The destination answered, but not 2xx. |
Errored | errored | The destination was unreachable (DNS, refused, timeout). |
DeadLetter | gave up | Retries exhausted. A replay starts it fresh. |
Replay re-delivers any stored request on demand: one at a time (the outcome returns inline) or in bulk (queued through the same pipeline, outcomes land in the attempt history). Replaying is always safe on the vault's side: it re-sends exactly what was captured.
Where next?
- Quickstart: dashboard: capture your first webhook on the Free plan
- CI testing mode: ephemeral endpoints and the await API
- API reference: every operation on these three nouns