In this section · Localhost, streams and the API

Use the REST API

Read captured requests, change the response and automations, and delete a URL from your own scripts, using the same JSON API the inspector uses.

The inspector is built on a small JSON API, and you can call it yourself. It's useful for scripts and tests around your own URLs: fetching what a URL caught, setting a response before a test, or cleaning up afterwards.

Before you start

  • Find the URL's ID and dashboard key. They're in the dashboard link, after the #: https://webhook.stream/inspect/#ID.KEY. To get the link, click Stream and open Share this inspector. The commands on the Forward to localhost tab also contain both.
  • The key gives full control of the URL. Keep it out of public repositories and logs.

Make a call

Every call goes to https://webhook.stream/api/endpoints/YOUR_ID with the key in an Authorization header:

curl https://webhook.stream/api/endpoints/YOUR_ID/requests \
  -H "Authorization: Bearer YOUR_KEY"

What you can do

Method and path Does
GET / The URL, its expiry, counts, limits, response and automations
GET /requests?limit=&before= Request summaries, newest first. before takes a sequence number, for paging
GET /requests?after=&limit= Full requests with bodies, oldest first. Use this for exports
GET /requests/REQUEST_ID One request, with its headers, body and deliveries
DELETE /requests/REQUEST_ID Delete one request
DELETE /requests Delete every request
PUT /response Replace the response settings
PUT /actions Replace the list of automations
GET /events The live event stream. See Follow requests with the event stream
DELETE / Delete the URL and everything it holds

The paths are relative to https://webhook.stream/api/endpoints/YOUR_ID. Request bodies are JSON in the same shape as the GET / reply. The easiest way to get a PUT right is to set things up once in the inspector, read them back with GET /, and reuse that.

Limits

The API allows 300 calls a minute from one client. Beyond that it answers 429 with a Retry-After header saying how many seconds to wait.

If something goes wrong

Answer Means
401 The key is missing, wrong, or not sent as Bearer
400 The body was rejected. The message in the reply says why, as the inspector would
404 No such request, or a mistyped path
410 The URL has expired or been deleted
429 Too many calls. Wait for the Retry-After time