In this section
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 |
