Inspect API Reference
Introduction
The Inspect API creates Inspect Source URLs and reads the requests they capture. A Source URL is a free, disposable webhook test URL, so the API lets a test or an AI agent create one, send to it, and read what arrived, with no account.
The API calls a Source URL a Source, so that's the word you'll see in the reference below and in its JSON.
The Inspect API is in early beta (
0.2.0). The contract may change.
Everything lives on the inspect.hookdeck.com host. Creation is proxied to Hookdeck server-side, so you only ever handle inspect.hookdeck.com URLs.
Base URL: https://inspect.hookdeck.com
The create response names both of a Source URL's addresses:
ingest_url(inspect.hookdeck.com/e/<id>) is the Source URL itself, which captures requests.inspect_url(inspect.hookdeck.com/<id>) is its page, where you read them.
The create response also has a requests_url. A GET to it waits up to 25 seconds for the Source URL's next request and returns it as JSON, so there's no need to poll. If nothing arrives in time, the reply has a URL to resume waiting from the same point. Without a wait, /<id>/requests reads a Source URL's requests from the start, oldest first, a page at a time.
Each captured request comes back with its method, path, query string, headers, and body. Every request also has a body_url, which downloads its exact bytes.
The Hookdeck REST API at api.hookdeck.com is a separate API with its own authentication, resources, and documentation. Nothing here applies to it.
The OpenAPI description is published at inspect.hookdeck.com/openapi.json, and a guide for AI agents at inspect.hookdeck.com/llms.txt.
Authentication
There is none. Every endpoint is public, and creating a Source URL requires no account.
Access is granted by knowing a Source URL's ID. Anyone with the ID can send requests to it and read the requests it captured, and opening it in a browser also lets them manage it. That's what makes a test URL shareable with a teammate.
So treat a Source URL like a key, and keep it out of anywhere public. Don't send anything through an Inspect Source URL you wouldn't want anyone holding the link to read. For authenticated access control, use an Event Gateway project, which needs a Hookdeck account.
Keep the cli_key secret
The create response includes a cli_key. It connects the Hookdeck CLI to your Source URLs, so hookdeck listen can forward their requests to your machine. Anyone holding it can listen to them and forward their requests, so don't share it, log it, or paste it into a prompt.
It isn't a credential for this API, which needs none.
Rate limits
| Endpoint | Limit |
|---|---|
POST / | 60 Source URLs created per minute |
GET /{id}, GET /{id}/requests, GET /{id}/requests/{request_ | 60 calls per minute, per client IP and Source URL |
Exceeding a limit returns 429 Too Many Requests with a Retry-After header giving the seconds to wait.
Creation is limited per client IP by default. If you replay the session cookie, it tracks that session instead of the IP it's called from.
A call that waits for a request counts once, however long it waits. A waiting caller makes two or three calls a minute, so the read limit only stops something calling in a loop.
The X-RateLimit-* headers on a create reply come from Hookdeck's general API limit, which is higher. They don't count down to the creation limit above.
Ingestion to /e/{id} is not covered by these limits. It's subject to the platform limits.
Errors
Errors use conventional HTTP status codes. Most error replies have an error code and a note saying what went wrong and what to do next.
| Status | Meaning |
|---|---|
400 | An invalid timeout (0 to 90), limit (1 to 50), or next on /{id}/requests. The reply's read_url reads the Source URL again from the start. |
403 | A POST / sent from a web page on another site. Create Source URLs from a server, a script, or an agent. |
404 | No Source URL with that ID, or it was deleted. On a body download, it can also mean the Source URL has no request with that ID. |
405 | A method the URL doesn't take, such as a POST to an inspect URL. Requests to capture go to the ingest URL, which the reply includes. |
422 | The type isn't a supported Source Type, or the name uses characters other than letters, digits, - and _. The data array says which. |
429 | A rate limit was exceeded. Retry after the interval in Retry-After. |
502 | Hookdeck couldn't be reached. On POST /, a Source URL may have been created anyway, so check before creating another. On a read, retry the same URL. |
503 | Too many reads right now. Retry the same URL after the interval in Retry-After. |
Ingestion is the exception. A request to /e/{id} is answered with a JSON receipt describing the captured request, not the state of this API. A method the Source URL's type doesn't accept is answered 405, and the request is still captured, marked as rejected.
Sessions
The first create without a session returns a session cookie on .hookdeck.com, with SameSite=Strict and a fixed 90-day lifetime that doesn't slide with use.
Replaying that cookie on later creates keeps those Source URLs together, so they show up in the same list in the app. It's optional, and most callers won't need it. Save it on the first create with -c and send it back with -b.
Without it, each create stands alone. The Source URLs still work identically; they just aren't listed together.
Reading a Source URL needs no cookie, and creates no session.
Creating from a browser
Opening inspect.hookdeck.com in a browser creates a Source URL, or opens the one that browser already has. The create happens client-side, so it only works in a browser that runs JavaScript. A non-browser client gets the page and creates nothing.
Prefer POST / for anything programmatic.
Sources
Create a source. A source captures the HTTP requests sent to its URL so you can inspect them.
Create a source
The canonical programmatic create. Creates a Hookdeck Source and returns explicit URL fields — ingest_url (the /e/<id> ingestion URL) and inspect_url (the /<id> bin) — plus requests_url to wait for its requests, a note on what to do next, the resolved type, the name, a cli_key, and a cmd_hint (a ready-to-run Hookdeck CLI command). All request fields are optional. The request is handled server-side and the Source is returned in a single response (no redirect to follow). Unauthenticated calls create a guest account; replay the session cookie returned on the first call to create more Sources in the same guest account.
Ingestion
Send requests to a source. Inspect Sources accept every HTTP verb, so a source captures any request you point at it.
Send a request to a source
Ingestion for a Source. Inspect Sources accept all HTTP verbs (GET, POST, PUT, PATCH, DELETE) — RequestBin-style. Any method is captured as a Hookdeck Request; the HTTP response is the Source's configured response (200 by default). Inspecting a Source in a browser is a separate path (GET /{id}).
Inspection
Read a source and the requests it has captured.
Inspect a source
A Source. With ?format=json (or Accept: application/json), the Source and its 10 newest requests as JSON, with requests_url to wait for the next one. Anything else gets the Inspect page. Never captured as a request.
Not for sending requests
Writes to the inspect URL are not captured. Send requests to the ingest URL instead (also PUT, PATCH and DELETE).
Read and wait for requests
The requests not yet returned to the next cursor, oldest first, each once. Without next, from the start. When there are none and timeout is set, holds the call open up to timeout seconds and returns as soon as one arrives; on timeout, returns WaitTimeout with a resume URL. Requests can become readable a moment after they arrive and not always in order; a request up to 15 seconds late is still returned. Always Cache-Control: no-store.
Download a request's body
The request's body exactly as it arrived, text or binary, as a file download (application/octet-stream). The request's content-type header says what it was. Each request's body_url points here.