Documentation
How webhook.stream works
A reference for everything the product does. Each section stands alone, so jump to what you need.
Quick start
- Press Get a webhook URL. You are taken to the inspector with a new URL.
- Send that URL any HTTP request, or paste it into a provider's webhook settings.
- Watch the request arrive. Select it to see its headers, query, body and signature.
curl -X POST https://in.webhook.stream/YOUR_ID \
-H "Content-Type: application/json" \
-d '{"hello":"world"}'Webhook URLs
A URL looks like https://in.webhook.stream/<id>. It accepts every HTTP method, any path after the ID and any query string, so /<id>/stripe?env=test works and the extra path is recorded.
The URL is write-only. It can receive requests but cannot be used to read them. Reading needs the dashboard key.
The dashboard link and key
The inspector's address is https://webhook.stream/inspect/#<id>.<key>. Everything after the # stays in your browser and is not sent to any server when the page loads. The key authorises the API calls the inspector makes. Your browser remembers the URLs you have created; to open one elsewhere, copy the full link from Stream → Share this inspector.
Anyone holding the dashboard link can read captured requests and change the URL's settings. Share it accordingly.
Expiry and deletion
You choose a lifetime when you create a URL, from one hour to 7 days. At expiry the URL answers 410 Gone and all captured data and settings are erased. You can delete a URL earlier from the inspector's menu. A Pro pass extends a URL's life without changing it.
Limits
| Limit | Free | Pro pass |
|---|---|---|
| Stored body size per request | 512 KB | 1 MB |
| Requests kept (oldest dropped first) | 250 | 2,000 |
| Requests over a URL's lifetime | 25,000 | 1,000,000 |
| Requests per minute to one URL | 600 | |
| Automations | 3 | 10 |
| Automation deliveries | 30 a minute, 1,000 a day | 120 a minute, 10,000 a day |
| New URLs per client | 6 a minute, 30 a day | |
Larger bodies are accepted and truncated: the request is recorded with its true size and marked as truncated. Requests over a rate limit receive 429 with a Retry-After header and are not recorded.
Responses
By default a URL answers 200 with a small JSON body. Under Response you can set the status (200 to 599), content type, extra headers, body and a delay of up to ten seconds.
The body and header values are templates, which is how verification handshakes are handled:
| Handshake | Content type | Body template |
|---|---|---|
| Slack URL verification | application/json | {"challenge":"{{body.challenge}}"} |
| Meta, WhatsApp, Instagram | text/plain | {{query["hub.challenge"]}} |
| Microsoft Graph | text/plain | {{query.validationToken}} |
Responses are restricted on purpose. HTML is not an available content type, and redirects, cookies and a few security headers cannot be set. Every response is sent with a Content-Security-Policy that makes browsers treat it as inert data. These rules stop test URLs from being used to host pages or bounce visitors elsewhere.
Templates
Templates appear in response bodies, automation bodies and header values. A placeholder is an expression in double braces.
What you can reference
| Expression | Value |
|---|---|
body, body.a.b, body.items[0].sku | The parsed body: JSON, or form fields for form-encoded requests. For other content, the text. |
raw | The body as text, exactly as received. |
headers.x-github-event | A request header. Names are lower-case. |
query.page, query["hub.challenge"] | A query string parameter. |
request.id, request.method, request.path, request.url | The request itself. |
request.ip, request.country, request.timestamp, request.time | Sender address and country, and the time received (ISO 8601 and milliseconds). |
provider, event | The detected provider and event name, when recognised. |
endpoint.id, endpoint.url | The webhook URL that received the request. |
Use brackets for keys that contain dots or other punctuation: body["user.name"]. A missing value renders as nothing in text and as null in JSON.
Filters
Add filters after a pipe. They run left to right: {{body.email | trim | lower | default: "unknown"}}.
| Filter | Effect |
|---|---|
default: "x" | Uses the argument when the value is missing or empty. |
upper, lower, trim | Changes case or strips surrounding whitespace. |
truncate: 200 | Shortens text to a number of characters. |
json, pretty | Serialises the value as JSON, compact or indented. |
number, string | Converts the type. |
urlencode, base64, escape | Encodes for a URL, as base64, or for XML and HTML. |
length, first, last, keys, join: ", " | Works with arrays and objects. |
iso | Formats a Unix timestamp or date as ISO 8601. |
JSON templates keep their types
When the content type is JSON and the template is valid JSON, it is rendered structurally. A string that is exactly one placeholder takes the type of its value, and substituted text is escaped correctly.
{ "id": "{{body.id}}", "total": "{{body.total}}", "lines": "{{body.lines}}", "note": "Order {{body.id}} received" }{ "id": "ord_8f3k2", "total": 129, "lines": [{ "sku": "KB-75", "qty": 1 }], "note": "Order ord_8f3k2 received" }Templates are not a programming language. There are no loops, conditionals or user-defined code, so rendering is fast and bounded.
Automations
An automation runs when a request arrives and its conditions match. It sends one HTTP request. See the overview for examples.
- Conditions compare an expression (the same syntax as templates, without braces) with a value: equals, does not equal, contains, does not contain, starts with, ends with, exists, does not exist, is greater than, is less than. All must hold.
- Destination must be a public
https://URL on port 443. IP addresses, private hostnames, embedded credentials and this service are refused. - Body is either a template or the original bytes. Choosing the original body and passing along the sender's headers keeps signatures verifiable downstream.
- Delivery has an 8-second timeout. Redirects are not followed. A 2xx status counts as success.
- Failures are logged and not retried. After 15 consecutive failures the automation pauses until you re-enable it.
Every delivery identifies itself with these headers:
User-Agent: webhook.stream/1.0 (+https://webhook.stream/docs/#automations)
X-Webhook-Stream-Endpoint: <id of the URL that received the request>
X-Webhook-Stream-Request: <id of the captured request>
X-Webhook-Stream-Hop: 1A request that arrives carrying X-Webhook-Stream-Hop is recorded but never triggers automations, so two URLs cannot be chained into a loop. If you are receiving deliveries you did not ask for, send the endpoint header to abuse@webhook.stream.
Stream API
Follow a URL's requests as Server-Sent Events.
curl -N https://webhook.stream/api/endpoints/$ID/events \
-H "Authorization: Bearer $KEY"Browsers' EventSource cannot send headers, so this route alone also accepts the key as ?key=. Prefer the header wherever you can set one.
| Event | When | Data |
|---|---|---|
request | A request was captured | summary, and detail with headers and body. For bodies over 64 KB detail is null: fetch it by ID. |
delivery | An automation delivery finished | Status, timing and error for that attempt. |
removed, cleared | Requests were deleted | The request ID, where relevant. |
config | Response or automations changed | The new settings. |
gone | The URL expired or was deleted | The stream then closes. |
Resuming. Each request event has an id. Reconnect with a Last-Event-ID header (EventSource does this automatically) or ?after=<id> and the stream first replays up to 100 requests you missed. Bodies are text when they are valid UTF-8 ("encoding": "utf8") and base64 otherwise.
Forwarding to localhost
The forwarder is a single dependency-free script built on the stream API. It replays each captured request against a local URL, preserving method, path, query, headers and body.
curl -fsSL https://webhook.stream/cli.js | node - \
--id $ID --key $KEY \
--to http://localhost:3000/webhooksYou can read the script before running it, or save it and run node cli.js with the same arguments.
REST API
The inspector is built on a small JSON API that you can call directly. Authenticate with Authorization: Bearer <dashboard key>. The base is https://webhook.stream/api/endpoints/<id>.
| Method and path | Purpose |
|---|---|
GET / | The URL, its expiry, counters, limits, response and automations. |
GET /requests?limit=&before= | Request summaries, newest first. before is a sequence number. |
GET /requests?after=&limit= | Full requests with bodies, oldest first. Use for export. |
GET /requests/<rid> | One request with headers, body and deliveries. |
DELETE /requests/<rid>, DELETE /requests | Delete one request, or all of them. |
PUT /response | Replace the response configuration. |
PUT /actions | Replace the list of automations. |
GET /events | The Server-Sent Events stream. |
DELETE / | Delete the URL and everything it holds. |
The API allows 300 requests a minute per client. It is intended for scripts and tests around your own URLs.
Notifications
The bell in the inspector turns on desktop notifications for requests that arrive while the tab is in the background. For alerts when the inspector is closed, add an automation that posts to Slack, Discord, Telegram or ntfy.
Keyboard shortcuts
| Key | Action |
|---|---|
j / k or arrow keys | Next and previous request |
/ | Focus the filter |
c | Copy the webhook URL |