> ## 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 into a configured webhook endpoint (PUT alias of ingestWebhookEvent)
> PUT alias; behaviour is identical to the POST operation.
## OpenAPI
````yaml /openapi.json put /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}:
put:
tags:
- Ingest
summary: >-
Ingest into a configured webhook endpoint (PUT alias of
ingestWebhookEvent)
description: PUT alias; behaviour is identical to the POST operation.
operationId: ingestWebhookEventPut
parameters:
- name: ingest_key
in: path
required: true
description: The plaintext ingest key.
schema:
type: string
- name: slug
in: path
required: true
description: >-
Webhook slug in the key's tenant; '-v' pins a
version, a bare slug takes the newest enabled one.
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: >-
Optional; a repeat key short-circuits with 200 before quota is
charged.
schema:
type: string
- name: X-Hookie-Signature
in: header
required: false
description: >-
Required only when the ingest key has require_signature. Format
't=,v1='.
schema:
type: string
requestBody:
required: false
description: >-
Identical to the POST form: form encodings flattened, everything else
parsed as JSON, empty body becomes {}, 1,000,000-byte cap.
content:
application/json:
schema:
description: Any JSON 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
required:
- filename
- type
- size
properties:
filename:
type: string
type:
type: string
size:
type: integer
responses:
'200':
description: Idempotent replay under an existing Idempotency-Key.
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; 'routed' holds the webhook rule's name, or is empty when its
conditions did not match.
content:
application/json:
schema:
type: object
required:
- submission_id
- routed
- records
additionalProperties: false
properties:
submission_id:
type: string
routed:
type: array
items:
type: string
records:
type: integer
'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'' or ''Invalid signature''.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'error: ''Source IP not allowed''.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'error: ''Unknown ingest key'' or ''Unknown webhook endpoint''.'
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 (retry_after: 10) or monthly quota (upgrade_url +
retry_after: 3600).
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', 'Could not store submission', or
'Webhook rule is malformed'.
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.
````