Documentation

How webhook.stream works

A reference for everything the product does. Each section stands alone, so jump to what you need.

Quick start

  1. Press Get a webhook URL. You are taken to the inspector with a new URL.
  2. Send that URL any HTTP request, or paste it into a provider's webhook settings.
  3. Watch the request arrive. Select it to see its headers, query, body and signature.
Your first request
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 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

LimitFreePro pass
Stored body size per request512 KB1 MB
Requests kept (oldest dropped first)2502,000
Requests over a URL's lifetime25,0001,000,000
Requests per minute to one URL600
Automations310
Automation deliveries30 a minute, 1,000 a day120 a minute, 10,000 a day
New URLs per client6 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:

HandshakeContent typeBody template
Slack URL verificationapplication/json{"challenge":"{{body.challenge}}"}
Meta, WhatsApp, Instagramtext/plain{{query["hub.challenge"]}}
Microsoft Graphtext/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

ExpressionValue
body, body.a.b, body.items[0].skuThe parsed body: JSON, or form fields for form-encoded requests. For other content, the text.
rawThe body as text, exactly as received.
headers.x-github-eventA request header. Names are lower-case.
query.page, query["hub.challenge"]A query string parameter.
request.id, request.method, request.path, request.urlThe request itself.
request.ip, request.country, request.timestamp, request.timeSender address and country, and the time received (ISO 8601 and milliseconds).
provider, eventThe detected provider and event name, when recognised.
endpoint.id, endpoint.urlThe 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"}}.

FilterEffect
default: "x"Uses the argument when the value is missing or empty.
upper, lower, trimChanges case or strips surrounding whitespace.
truncate: 200Shortens text to a number of characters.
json, prettySerialises the value as JSON, compact or indented.
number, stringConverts the type.
urlencode, base64, escapeEncodes for a URL, as base64, or for XML and HTML.
length, first, last, keys, join: ", "Works with arrays and objects.
isoFormats 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.

Template
{ "id": "{{body.id}}", "total": "{{body.total}}", "lines": "{{body.lines}}", "note": "Order {{body.id}} received" }
Result
{ "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:

Headers added to deliveries
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: 1

A 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.

Follow a URL
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.

EventWhenData
requestA request was capturedsummary, and detail with headers and body. For bodies over 64 KB detail is null: fetch it by ID.
deliveryAn automation delivery finishedStatus, timing and error for that attempt.
removed, clearedRequests were deletedThe request ID, where relevant.
configResponse or automations changedThe new settings.
goneThe URL expired or was deletedThe 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.

Requires Node.js 20 or newer
curl -fsSL https://webhook.stream/cli.js | node - \
  --id $ID --key $KEY \
  --to http://localhost:3000/webhooks

You 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 pathPurpose
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 /requestsDelete one request, or all of them.
PUT /responseReplace the response configuration.
PUT /actionsReplace the list of automations.
GET /eventsThe 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

KeyAction
j / k or arrow keysNext and previous request
/Focus the filter
cCopy the webhook URL