> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Example payloads for each exposed event type, and how to verify a delivery (both signature schemes)

> For each dataset the portal exposes (#198, PORT-11): the JSON envelope Hookie POSTs, around the shape of the dataset's latest record with every value replaced (strings `"<string>"`, numbers 0, booleans false, arrays one element, at most 6 levels and 50 keys). A portal's customers share its datasets, so no value from a record is ever returned — only field names. A dataset with no record yet shows the envelope with empty `data`. The response documents both signatures every delivery carries over one timestamp: `signature` (Hookie-Signature) and, since #245, `standard_webhooks` (the Standard Webhooks `webhook-id` / `webhook-timestamp` / `webhook-signature` set added by #192, DLV-12), which a receiver can check with an official `standardwebhooks` library by passing the `whsec_` signing secret as is.



## OpenAPI

````yaml /openapi.json get /portal/api/examples
openapi: 3.1.0
info:
  title: Hookie API
  version: 1.0.0
  summary: Capture, route and deliver webhooks.
  description: >-
    Hookie exposes three HTTP surfaces.


    **Ingest + streaming** is the public plane. A path-form endpoint URL
    authenticates by its own high-entropy slug — there is no key, token or
    cookie — and an `ik_live_…` ingest key authenticates the `/v1/*` routes. An
    endpoint URL files each payload into the endpoint's own dataset through the
    endpoint's own criteria and mappings (none means the whole payload, as one
    record); `/v1/ingest/{ingest_key}/{dataset}` stores the payload whole into
    the named dataset. Project mapping rules are evaluated on exactly one shape,
    `POST /v1/ingest/{ingest_key}` with no dataset segment, and never on an
    endpoint URL.


    **The customer portal API** is a separate, token-authed surface for your end
    customers, scoped to one portal and one customer.


    **The admin API** drives the console. It accepts either a browser session or
    an OAuth bearer token from a connected coding agent — the same routes, the
    same validation, the same audit trail. An agent's authority is its user's
    workspace role narrowed to the scopes granted in the console. It also
    accepts an **admin API key** (`hk_…`, Settings → API keys) for CI,
    infrastructure-as-code and vendor backends: the key acts as the member who
    created it, capped at the key's role (viewer, developer or admin — never
    billing or platform administration), optionally limited to one project, with
    an optional expiry and IP allowlist. Keys are stored as a SHA-256 hash and
    shown once; if their creator leaves the workspace they stop working. The
    same key works on the hosted MCP server at `/mcp`.


    **A refused agent is told how to proceed.** An agent's grant is one rung of
    a ladder — `hookie:read` < `hookie:write` < `hookie:manage` — and a call
    above it answers 403 with `code: "agent_scope_insufficient"`, the
    `required_scope`, the `granted_scopes` and a `manage_url` to the console
    page where its user widens it. When the user's own role is the limit the
    code is `insufficient_role` and there is no link, because no grant can
    exceed the user; billing, platform admin, managing connected agents and
    destination signing secrets answer `agent_not_permitted` at every scope. A
    human in the console still reads `Insufficient role`.


    **A suspended workspace** (an operator action, for abuse or non-payment)
    answers every surface with 403 and `reason: "workspace_suspended"`: ingest
    (endpoint URLs and ingest keys), `/v1/data` and `/v1/stream` refuse before
    anything is stored or counted, and every admin API write — console, OAuth
    agent or hosted MCP alike — is refused except billing, platform admin,
    connected-agent management, revoking an API key and the POST-bodied
    searches. The customer portal API is read-only in the same way: destination
    writes answer 403 `workspace_suspended`. Reads keep working. Nothing is sent
    while it is suspended: pending deliveries are paused, workflow runs already
    under way are paused, open `/v1/stream` connections are closed, and cron
    triggers, database sources and WebSocket listeners stop. Reinstating sends
    the paused deliveries, resumes the paused workflow runs where they stopped,
    and resumes the rest; no stored data is lost.


    **Rate limits.** `/admin/api/*` and `/mcp` allow about 100 requests every 10
    seconds per credential — per API key, per connected agent, or per signed-in
    person. Over that, the answer is 429 with `Retry-After` (seconds). Like
    every burst limit here, ingest's included, it is a best-effort guard rather
    than an exact count: it is counted separately at each Cloudflare location
    and catches up within seconds, so a short burst can get through above it.
    The monthly event quota is the exact count.


    **Idempotency.** A `POST` to `/admin/api/*` may carry an `Idempotency-Key`
    header (1–255 printable characters, e.g. a UUID). The first request runs and
    its response is stored for 24 hours; a retry with the same key from the same
    credential, with the same path and body, gets that response back with
    `Idempotent-Replayed: true` and runs nothing. The same key with a different
    path, body or credential is refused with 422; a retry while the first
    request is still running gets 409. 5xx responses are not stored. `POST
    /admin/api/api-keys` refuses the header, because its response is a secret
    shown once and is never stored.


    **Versioning.** Every `/admin/api/*` and `/mcp` response carries
    `Hookie-Version` (currently `2026-09-29`). Additive changes — a new route, a
    new response field, a new optional parameter — ship under the current
    version, so clients must ignore fields they do not know. A breaking change
    gets a new dated version, announced in the changelog, and the previous
    version stays available for at least 12 months; a client pins one by sending
    `Hookie-Version` on its requests. A version this deployment does not serve
    is refused with 400 and the list of `supported_versions`.


    This document is generated from the request handlers and adversarially
    verified against them.
  contact:
    name: Hookie
    url: https://hookie.ai
  license:
    name: Proprietary
    url: https://hookie.ai/legal/terms
servers:
  - url: https://app.hookie.ai
    description: Production
  - url: https://app.preview.hookie.ai
    description: Preview
security: []
tags:
  - name: Ingest
    description: Send events to Hookie.
  - name: Streaming
    description: Tail events in real time over SSE or WebSocket.
  - name: Portal
    description: Token-authed surface for your end customers.
  - name: Projects
    description: Projects and their settings.
  - name: Routing
    description: Rules, endpoints, datasets and records.
  - name: Delivery
    description: Destinations, deliveries and replay.
  - name: Workflows
    description: Multi-step workflows, triggers and AI agents.
  - name: Observability
    description: Search, correlation, stats and the audit log.
  - name: Workspace
    description: >-
      The workspace itself: its name and slug, admin API keys, data export and
      closure. There are no member invites or member routes yet (#258): a
      workspace has its owner, plus any admin the platform sets up.
  - name: Data API
    description: >-
      Read-only access to the datasets and columns a project exposes, with
      per-project keys.
  - name: Broadcast Logs
    description: >-
      Forward a project's logs and traces over OTLP/HTTP (JSON) to Datadog,
      Grafana Cloud, an OpenTelemetry Collector, PostHog or Sentry.
paths:
  /portal/api/examples:
    get:
      tags:
        - Customer Portal
      summary: >-
        Example payloads for each exposed event type, and how to verify a
        delivery (both signature schemes)
      description: >-
        For each dataset the portal exposes (#198, PORT-11): the JSON envelope
        Hookie POSTs, around the shape of the dataset's latest record with every
        value replaced (strings `"<string>"`, numbers 0, booleans false, arrays
        one element, at most 6 levels and 50 keys). A portal's customers share
        its datasets, so no value from a record is ever returned — only field
        names. A dataset with no record yet shows the envelope with empty
        `data`. The response documents both signatures every delivery carries
        over one timestamp: `signature` (Hookie-Signature) and, since #245,
        `standard_webhooks` (the Standard Webhooks `webhook-id` /
        `webhook-timestamp` / `webhook-signature` set added by #192, DLV-12),
        which a receiver can check with an official `standardwebhooks` library
        by passing the `whsec_` signing secret as is.
      operationId: getPortalExamples
      responses:
        '200':
          description: Examples and the signature scheme.
          content:
            application/json:
              schema:
                type: object
                required:
                  - examples
                  - signature
                  - standard_webhooks
                  - headers
                properties:
                  examples:
                    type: array
                    items:
                      type: object
                      required:
                        - dataset
                        - source
                        - payload
                      properties:
                        dataset:
                          type: string
                        source:
                          type: string
                          enum:
                            - recent_record_redacted
                            - none
                        payload:
                          type: object
                          properties:
                            id:
                              type: string
                            dataset:
                              type: string
                            received_at:
                              type: string
                            data:
                              type: object
                  signature:
                    type: object
                    properties:
                      header:
                        type: string
                        enum:
                          - Hookie-Signature
                      format:
                        type: string
                      signed_content:
                        type: string
                      note:
                        type: string
                  standard_webhooks:
                    type: object
                    description: >-
                      The Standard Webhooks signature
                      (https://www.standardwebhooks.com) every delivery also
                      carries (DLV-12). `webhook-id` is the delivery id, so a
                      retry repeats it; during a secret rotation
                      `webhook-signature` carries one space-separated `v1,`
                      value per live secret.
                    required:
                      - headers
                      - format
                      - signed_content
                      - secret
                      - libraries
                      - spec
                      - note
                    properties:
                      headers:
                        type: array
                        items:
                          type: string
                          enum:
                            - webhook-id
                            - webhook-timestamp
                            - webhook-signature
                      format:
                        type: string
                      signed_content:
                        type: string
                      secret:
                        type: string
                        description: >-
                          How to hand the signing secret to a library: the
                          `whsec_` value exactly as shown, not stripped or
                          decoded.
                      libraries:
                        type: string
                        format: uri
                        description: The official Standard Webhooks libraries.
                      spec:
                        type: string
                        format: uri
                      note:
                        type: string
                  headers:
                    type: array
                    items:
                      type: string
                    description: >-
                      Every header a delivery carries: Hookie's own and the
                      Standard Webhooks set.
              example:
                examples:
                  - dataset: orders
                    source: recent_record_redacted
                    payload:
                      id: <event id>
                      dataset: orders
                      received_at: <ISO 8601 timestamp>
                      data:
                        order_id: <string>
                        amount: 0
                signature:
                  header: Hookie-Signature
                  format: t=<unix seconds>,v1=<hex HMAC-SHA256>
                  signed_content: <t>.<raw request body>
                  note: >-
                    During a secret rotation the header carries one v1 per live
                    secret for 24 hours; accept the request when any v1 matches.
                standard_webhooks:
                  headers:
                    - webhook-id
                    - webhook-timestamp
                    - webhook-signature
                  format: v1,<base64 HMAC-SHA256>
                  signed_content: <webhook-id>.<webhook-timestamp>.<raw request body>
                  secret: >-
                    Pass your whsec_ signing secret to the library exactly as
                    shown. Do not strip the prefix or decode it: the library
                    does both.
                  libraries: >-
                    https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries
                  spec: https://www.standardwebhooks.com
                  note: >-
                    webhook-id is the delivery id, so a retry repeats it. During
                    a secret rotation webhook-signature carries one
                    space-separated v1 per live secret for 24 hours; a library
                    accepts the request when any matches.
                headers:
                  - Hookie-Signature
                  - Hookie-Event-Id
                  - Hookie-Delivery-Id
                  - Idempotency-Key
                  - webhook-id
                  - webhook-timestamp
                  - webhook-signature
        '401':
          description: >-
            Missing, malformed, revoked, expired token, or the portal is
            disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Rate limited: each portal token may make 60 calls a minute across
            the portal API. Retry after the `Retry-After` header (60 seconds).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - portalTokenHeader: []
        - portalSession: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable reason.
        retry_after:
          type: integer
          description: Seconds to wait. Present on 429.
        upgrade_url:
          type: string
          format: uri
          description: Present only on a monthly-quota 429.
        reason:
          type: string
          description: >-
            Machine-readable reason, where the status alone is ambiguous.
            `workspace_suspended` (403): the workspace is suspended;
            `delivery_allowance_exhausted` (429): a replay was refused because
            the monthly delivery allowance is used. `endpoint_disabled` (503):
            the endpoint is switched off; `handshake_failed`: a provider
            URL-verification challenge could not be answered (#193).
            `missing_header`, `bad_signature`, `stale_timestamp` (401): an
            endpoint's provider signature check failed; `scheme` names the
            check.
        code:
          type: string
          enum:
            - agent_scope_insufficient
            - insufficient_role
            - agent_not_permitted
          description: >-
            Present on a 403 to an OAuth-connected agent.
            `agent_scope_insufficient`: the agent's grant is below what the call
            needs, and widening it would let the call through (see
            `required_scope` and `manage_url`). `insufficient_role`: the user's
            OWN workspace role does not allow the call, so no grant can — and
            roles cannot be changed in the product yet, so the call is one for
            the workspace owner. `agent_not_permitted`: no connected agent may
            do this at any scope (billing, platform admin, managing connected
            agents, a destination's signing secret).
        required_scope:
          type: string
          enum:
            - hookie:read
            - hookie:write
            - hookie:manage
          description: 'With `code`: the scope the refused call needs.'
        granted_scopes:
          type: array
          items:
            type: string
          description: 'With `code`: the scopes the agent''s grant holds now.'
        manage_url:
          type: string
          format: uri
          description: >-
            With `code: "agent_scope_insufficient"` only: the console's Settings
            → Connected agents page, opened on this agent
            (`…/#/settings/agents?client=<client_id>`), where its user widens
            the grant. The change applies on the agent's next request.
        scheme:
          type: string
          description: 'Present on a signature 401: the endpoint''s verification scheme.'
  securitySchemes:
    portalTokenHeader:
      type: http
      scheme: bearer
      description: >-
        A `hpt_…` customer portal token, as `Authorization: Bearer`. Stored
        hashed and looked up by its full SHA-256 hash; shown once at issue. The
        query string (`?token=`) is not accepted: a token there ends up in
        request logs and traces. A browser page trades the token for a
        `portalSession` cookie with POST /portal/api/session.
    portalSession:
      type: apiKey
      in: cookie
      name: __Host-hookie_portal
      description: >-
        The customer portal's session cookie, set by POST /portal/api/session:
        sealed (AES-GCM), HttpOnly, Secure, SameSite=None, Partitioned, and
        valid for 8 hours or until the token expires, whichever is sooner. It
        names the token rather than copying what it grants, so revoking the
        token or switching the portal off ends the session at once. Requests
        other than GET made with it must carry `X-Requested-With: fetch` (CSRF).

````