> ## 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. # Ingest an event through the public webhook URL > Public webhook URL, app.hookie.ai/{workspace}/{project}/{webhook}. POST ONLY: index.ts:190 gates the route on req.method === 'POST', so PUT/GET/OPTIONS on this path never reach the ingest handler — they fall through to the SPA asset handler and return the console HTML, not a 405 JSON. Only 3- or 4-segment paths match. ## OpenAPI ````yaml /openapi.json post /{workspace}/{project}/{webhook} 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. Whenever the URL names a dataset the payload is stored whole into it; project mapping rules are evaluated on exactly one shape, `POST /v1/ingest/{ingest_key}` with no dataset segment. **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. 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: Members, connected agents, SSO and billing. paths: /{workspace}/{project}/{webhook}: post: tags: - Ingest summary: Ingest an event through the public webhook URL description: >- Public webhook URL, app.hookie.ai/{workspace}/{project}/{webhook}. POST ONLY: index.ts:190 gates the route on req.method === 'POST', so PUT/GET/OPTIONS on this path never reach the ingest handler — they fall through to the SPA asset handler and return the console HTML, not a 405 JSON. Only 3- or 4-segment paths match. operationId: ingestPathForm parameters: - name: workspace in: path required: true description: >- Workspace (tenant) slug. Must not be one of the reserved roots reserved for app internals (api, admin, stripe, v1, assets, settings, favicon.ico, robots.txt, sitemap.xml, index.html, app.js, styles.css, export.js, portal, brand, trial-info, .well-known, mcp) — those never reach the ingest handler. schema: type: string - name: project in: path required: true description: Project slug within the workspace. schema: type: string - name: webhook in: path required: true description: >- Webhook slug. This high-entropy slug IS the credential — no key, token or cookie is sent. Only an enabled webhook (enabled = 1) matches. schema: type: string - name: Idempotency-Key in: header required: false description: >- Optional. If a submission already exists for this tenant with the same key, the request short-circuits with 200 before the monthly quota is charged, so retries are free. schema: type: string requestBody: required: false description: >- Content-Type selects the parser: 'application/x-www-form-urlencoded' and 'multipart/form-data' are flattened into a shallow object (a field that repeats becomes an array; a file part becomes {filename, type, size} and its BYTES ARE DISCARDED; field names are kept verbatim and flat, so an input named user.email stays the key 'user.email'). ANY other Content-Type — including a missing or wrong one — is parsed as JSON. An empty body is accepted and becomes {}. A payload that is not a JSON object (array or scalar) is wrapped as {"value": } before it is stored as a record. Bodies over 1,000,000 bytes are rejected with 413. content: application/json: schema: description: >- Any JSON value. Objects are stored field-for-field; arrays and scalars are wrapped as {value: }. application/x-www-form-urlencoded: schema: type: object additionalProperties: oneOf: - type: string - type: array items: type: string multipart/form-data: schema: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object description: File part descriptor; the bytes are not stored. required: - filename - type - size properties: filename: type: string type: type: string size: type: integer responses: '200': description: >- Idempotent replay — a submission with this Idempotency-Key already exists for the tenant. No quota is charged when the duplicate is detected up front; a request that loses the unique-index race has already been counted against the monthly quota. content: application/json: schema: type: object required: - submission_id - idempotent additionalProperties: false properties: submission_id: type: string description: id of the submission stored by the first request idempotent: type: boolean enum: - true '201': description: >- Stored and routed. The payload is identity-routed into the webhook's configured dataset, so 'routed' holds exactly that dataset name. Routing errors after the submission row is written are swallowed (the raw submission is never lost), which surfaces as routed: [] and records: 0. content: application/json: schema: type: object required: - submission_id - routed - records additionalProperties: false properties: submission_id: type: string routed: type: array items: type: string description: the dataset the record landed in records: type: integer description: routed.length '400': description: >- Body could not be parsed. error is 'Body must be valid JSON' or 'Body is not valid multipart/form-data'. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- error: 'Source IP not allowed'. The Cloudflare client IP must match BOTH the webhook's IP allowlist and the tenant's (an empty allowlist matches everything; a request with no client IP skips the check). The block is written to the audit log. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- error: 'Unknown endpoint'. Uniform miss for any of: unknown workspace slug, unknown project slug, unknown or disabled webhook slug. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: >- error: 'Body exceeds 1000000 bytes'. Checked against Content-Length first, then against the buffered byte length. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Two distinct cases, both with a retry_after body field and NO Retry-After response header. Edge burst limit: {error: 'Rate limit exceeded', retry_after: 10}. Monthly plan quota: {error: 'Monthly event quota exceeded', upgrade_url: '/settings/billing', retry_after: 3600}. Only the quota case carries upgrade_url. Both limiters fail open if their backing service is unavailable. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: retry_after: type: integer description: >- seconds: 10 for the edge rate limit, 3600 for the monthly quota upgrade_url: type: string format: uri description: monthly-quota 429 only '500': description: >- error: 'Could not store submission' — the submissions insert failed with no idempotency winner to fall back to. content: application/json: schema: $ref: '#/components/schemas/Error' security: [] 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. ````