Console API Reference

Authentication

There is none. Every endpoint is public, and creating a source requires no account.

Access is granted by knowing a source's ID. Anyone with the ID can send requests to it, read the requests it captured, and open it in the Console. That's what makes a test URL shareable with a teammate.

That makes the ID a capability, not a secret. Don't send anything through a Console source you wouldn't want anyone holding the link to read. For authenticated access control, use an Event Gateway project, which needs a Hookdeck account.

The cli_key is not a bearer token

The create response includes a cli_key. It exists for the Hookdeck CLI, which uses it to forward captured requests to your machine. It is not an API credential: passing it as Authorization: Bearer will not authenticate a request to this API or to api.hookdeck.com.

Rate limits

Creating sources is rate limited.

Exceeding a limit returns 429 Too Many Requests with a Retry-After header giving the seconds to wait.

Limits apply per client IP by default. If you replay the session cookie, they track that session instead of the IP it's called from.

Ingestion to /e/{id} is not covered by these limits. It's subject to the platform limits.

Errors

Errors use conventional HTTP status codes.

A 422 response carries the code, the status, and a data array naming what was rejected.

Ingestion is the exception: a request to /e/{id} returns whatever response the source is configured to return, 200 by default. That response describes the source, not the state of this API.

Sessions

The first unauthenticated create 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 sources together, so they show up in the same source list. 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 sources still work identically; they just aren't listed together.

Creating from a browser

GET /new creates a source and redirects to it. The create happens client-side, so it only works in a browser that runs JavaScript. A non-browser client gets the app shell and creates nothing.

Prefer POST / for anything programmatic. A link that creates on GET is a convenience, not an API.

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 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 provision a guest workspace; replay the session cookie returned on the first call to create additional Sources in the same workspace.

Create a source and open it in the Console

A browser-only convenience entry point — a handy link a person opens to create a Source and land in the Console. The server returns the Console app (200); the app then creates a new Source and performs a client-side redirect to that Source's inspect path (console.hookdeck.com/<id>). Because the create happens in the browser, non-browser clients (curl, crawlers that don't run JS) get the app shell and create nothing. Accepts an optional type query parameter; unknown values are ignored (lenient). For programmatic create, use POST / — this route is not a programmatic API.

Ingestion

Send requests to a source. Console 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. Console 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}), so a GET to /e/ is always captured, never treated as inspection.

Inspection

Read a source and the requests it has captured.

Inspect a source

Opens a Source for inspection. The representation is chosen by the Accept header:

• Accept: application/json → a JSON preview (SourcePreview) of the Source and its most recently captured requests, for programmatic inspection.
• Anything else (a browser's Accept: text/html, or no Accept) → the Console app, deep-linked to this Source.

Inspection is a distinct namespace from ingestion (/e/{id}), so a GET here is never captured as an event.