> ## 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 into a configured webhook endpoint using an ingest key

> Key-authenticated form of a webhook endpoint. PUT is accepted identically (ingestWebhookEventPut); any other method returns 405 {"error":"Use POST"}.



## OpenAPI

````yaml /openapi.json post /v1/webhooks/{ingest_key}/{slug}
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:
  /v1/webhooks/{ingest_key}/{slug}:
    post:
      tags:
        - Ingest
      summary: Ingest an event into a configured webhook endpoint using an ingest key
      description: >-
        Key-authenticated form of a webhook endpoint. PUT is accepted
        identically (ingestWebhookEventPut); any other method returns 405
        {"error":"Use POST"}.
      operationId: ingestWebhookEvent
      parameters:
        - name: ingest_key
          in: path
          required: true
          description: >-
            The plaintext ingest key (prefix lookup + constant-time SHA-256
            comparison). It authenticates the request; the tenant it belongs to
            scopes the webhook lookup.
          schema:
            type: string
        - name: slug
          in: path
          required: true
          description: >-
            Webhook slug within the key's tenant. A bare slug selects the most
            recently created enabled webhook with that base slug; a versioned
            slug of the form '<base>-v<version>' (version = 1+ digits,
            optionally .digits, e.g. 'orders-v2' or 'orders-v2.1') pins that
            exact enabled version. Only enabled webhooks match.
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional. A repeat key short-circuits with 200 — after the webhook
            slug is resolved, but before the monthly quota is charged.
          schema:
            type: string
        - name: X-Hookie-Signature
          in: header
          required: false
          description: >-
            Required only when the ingest key has require_signature set (this
            route uses the KEY's signature setting and signing secret, not the
            webhook's). Format 't=<unix-timestamp>,v1=<hex>', v1 = HMAC-SHA-256
            over '<t>.<raw body>'.
          schema:
            type: string
      requestBody:
        required: false
        description: >-
          Form encodings are flattened (repeats become arrays, file parts become
          {filename, type, size} with the bytes discarded); every other
          Content-Type is parsed as JSON; an empty body becomes {}. The parsed
          payload is evaluated against the webhook's rule conditions and
          reshaped by its mappings (empty conditions match everything, empty
          mappings are identity). Over 1,000,000 bytes yields 413.
        content:
          application/json:
            schema:
              description: >-
                Any JSON value; its shape is whatever the webhook's rule
                conditions and mappings expect.
          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
                    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 (or a concurrent insert lost the unique race).
            No quota charged.
          content:
            application/json:
              schema:
                type: object
                required:
                  - submission_id
                  - idempotent
                additionalProperties: false
                properties:
                  submission_id:
                    type: string
                  idempotent:
                    type: boolean
                    enum:
                      - true
        '201':
          description: >-
            Stored. If the webhook rule's conditions are empty or match the
            payload, the rule is applied and 'routed' holds its NAME; if the
            conditions do not match, the submission is still stored and the
            response is 201 with routed: [] and records: 0. A swallowed routing
            failure looks the same.
          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 applied rule's name, or empty when the conditions did
                      not match
                  records:
                    type: integer
                    description: routed.length
        '400':
          description: >-
            error: 'Body must be valid JSON' or 'Body is not valid
            multipart/form-data'.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Signature-required keys only: 'Signature required' or 'Invalid
            signature'.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            error: 'Source IP not allowed' — the client IP failed the key
            allowlist or the tenant allowlist; the block is audited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Two messages. 'Unknown ingest key' — unknown/revoked key, hash
            mismatch or missing tenant row. 'Unknown webhook endpoint' — no
            enabled webhook with that slug in the key's tenant. The slug is
            resolved BEFORE quota is charged and before the submission is
            stored, so a bad slug costs nothing and leaves no pending row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'error: ''Body exceeds 1000000 bytes''.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Edge rate limit {error: 'Rate limit exceeded', retry_after: 10} or
            monthly quota {error: 'Monthly event quota exceeded', upgrade_url:
            '<APP_ORIGIN>/settings/billing', retry_after: 3600}. retry_after is
            a body field; no Retry-After header is sent.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      retry_after:
                        type: integer
                      upgrade_url:
                        type: string
                        format: uri
        '500':
          description: >-
            error: 'Key misconfigured' (signing secret could not be decrypted),
            'Could not store submission', or 'Webhook rule is malformed' (the
            rule's conditions/mappings JSON failed to parse — note the
            submission has already been stored and the quota already charged at
            this point).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ingestKey: []
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.
  securitySchemes:
    ingestKey:
      type: http
      scheme: bearer
      description: >-
        An `ik_live_…` ingest key. Stored hashed; the plaintext is returned once
        at creation.

````