API reference

Hookie exposes three HTTP surfaces: the public ingest + streaming API (authenticated by a path-form endpoint URL or an ik_live_… ingest key), the token-authed customer portal API for your end customers, and the session-authenticated admin API that drives the console.

Ingest

# Path-form endpoint (recommended) — the webhook slug IS the credential
POST /{workspace}/{project}/{webhook}            # store into the endpoint's dataset
POST /{workspace}/{project}/{webhook}/{dataset}  # override the dataset

# Ingest-key plane (machine-to-machine) — Authorization by key
POST /v1/ingest/{ingest_key}            # route via your rules
POST /v1/ingest/{ingest_key}/{dataset}  # route straight to {dataset}
POST /v1/webhooks/{ingest_key}/{slug}   # a configured webhook endpoint

Bodies are JSON. The path-form endpoint stores the whole payload into the endpoint's dataset (or run project rules to split it). For the ingest-key plane, omitting {dataset} runs your mapping rules; including one stores a single record in that dataset. Endpoints can additionally require an HMAC signature and an IP allowlist.

Streaming

GET  /v1/stream                         # live tail (SSE or WebSocket)

See Live streaming for SSE/WebSocket details and resume.

Customer portal API

# Authorization: Bearer <portal token>   (or ?token=…)
GET  /portal/api/me                     # portal + customer info + event types
GET  /portal/api/event-types            # datasets the portal exposes
GET  /portal/api/destinations           # the customer's destinations
POST /portal/api/destinations           # create (https only; signing secret shown once)
PUT  /portal/api/destinations/{id}      # enable/disable or change URL
GET  /portal/api/deliveries             # deliveries to the customer's destinations

A separate, token-authed surface for your end customers, scoped to one portal + customer — see Customer portal for issuing tokens and embedding.

Admin API

The console's admin API lives at /admin/api/projects/{pid}/…, is session-authenticated, and drives everything you see in the app — sign in to explore it. Project-scoped resources:

Resources	Covers
`datasets · submissions · rules · webhooks`	Routing: raw capture, mapping rules, versioned endpoints.
`ingest-keys · destinations · deliveries`	Credentials, outbound sinks, delivery log + replay.
`sources · triggers · cron-triggers · ws-triggers`	DB polling, AI triggers, scheduled + WebSocket sources.
`workflows · workflow-instances · ai-agents`	Multi-step workflows, instance history, reusable AI agents.
`search/{events,deliveries,ai-runs} · search/correlate/{id}`	Filtered search + cross-entity correlation.
`portals (+ /tokens)`	Customer portals and per-customer access tokens.
`audit · sso · destination-presets · source-presets`	Audit log (+ CSV export), SAML config, integration presets.

Request headers

Header	Purpose
`Content-Type`	application/json (request bodies are JSON).
`Idempotency-Key`	Optional. Dedupes retries; the same submission is returned and never double-counted.
`X-Hookie-Signature`	Required only for keys with signature enforcement. t=<unix>,v1=<hex> over <t>.<body>.
`Authorization`	Bearer <ingest_key> for GET /v1/stream (or ?key= for EventSource).

Response codes

Status	Meaning
`201 Created`	Event stored and routed.
`200 OK`	Idempotent replay — the original submission is returned.
`400 Bad Request`	Body isn't valid JSON.
`401 Unauthorized`	Missing/invalid inbound signature (when required), or missing stream key.
`403 Forbidden`	Source IP not in the allowlist.
`404 Not Found`	Unknown ingest key or webhook endpoint.
`429 Too Many Requests`	Edge rate limit or monthly quota exceeded (see Retry-After).

Outbound (to your endpoints)

Deliveries are signed and carry Hookie-Signature, Hookie-Event-Id, and Hookie-Delivery-Id. Delivery is at-least-once and unordered — dedupe on the event id and verify the signature.