Ingest an event with an ingest key (PUT alias of ingestEvent)
curl --request PUT \
--url https://app.hookie.ai/v1/ingest/{ingest_key} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '"<unknown>"'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify('<unknown>')
};
fetch('https://app.hookie.ai/v1/ingest/{ingest_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.hookie.ai/v1/ingest/{ingest_key}"
payload = "<unknown>"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text){
"submission_id": "<string>",
"idempotent": true,
"deduplicated_by": "idempotency-key"
}{
"submission_id": "<string>",
"routed": [
"<string>"
],
"records": 123,
"fallback": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "quota_exceeded",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true,
"limit": 123,
"reset_at": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}Ingest
Ingest an event with an ingest key (PUT alias of ingestEvent)
PUT is accepted verbatim — the handler’s only method check allows POST and PUT, and nothing downstream branches on the method. Not idempotent in the HTTP sense: each PUT stores a new submission unless an Idempotency-Key repeats. Every stored submission keeps the request’s method, a filtered header map, the query string, the Content-Type and the source IP (ING-3, #193), shown on the record (GET …/records/) and on correlate as request. Credentials are never stored: Authorization, Proxy-Authorization, Cookie and any header or query parameter named like a credential (key, api-key, token, secret, password, session, auth) is stored as “[redacted]”; Cloudflare and proxy hop headers (cf-, x-forwarded-, x-real-ip, true-client-ip, cdn-loop, host) are dropped.
PUT
/
v1
/
ingest
/
{ingest_key}
Ingest an event with an ingest key (PUT alias of ingestEvent)
curl --request PUT \
--url https://app.hookie.ai/v1/ingest/{ingest_key} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '"<unknown>"'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify('<unknown>')
};
fetch('https://app.hookie.ai/v1/ingest/{ingest_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.hookie.ai/v1/ingest/{ingest_key}"
payload = "<unknown>"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text){
"submission_id": "<string>",
"idempotent": true,
"deduplicated_by": "idempotency-key"
}{
"submission_id": "<string>",
"routed": [
"<string>"
],
"records": 123,
"fallback": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "quota_exceeded",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true,
"limit": 123,
"reset_at": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}{
"error": "<string>",
"retry_after": 123,
"upgrade_url": "<string>",
"reason": "<string>",
"code": "agent_scope_insufficient",
"required_scope": "hookie:read",
"granted_scopes": [
"<string>"
],
"manage_url": "<string>",
"scheme": "<string>",
"max_members": 123,
"members": 123,
"customer_id": "<string>",
"customer_name": "<string>",
"account_id": "<string>",
"terms_version": "<string>",
"claim_required": true
}Authorizations
An ik_live_… ingest key. Stored hashed; the plaintext is returned once at creation.
Headers
Optional; a repeat key short-circuits with 200 before quota is charged.
Required only when the key has require_signature. Format 't=,v1=', v1 = HMAC-SHA-256 over '.'.
Path Parameters
The plaintext ingest key (looked up by its full SHA-256 hash, #177; revoked and expired keys never match).
Body
application/jsonapplication/x-www-form-urlencodedmultipart/form-datatext/plainapplication/xmltext/csvapplication/x-ndjson
Identical to POST /v1/ingest/{ingest_key}: form encodings are flattened, anything else is parsed as JSON first and textual non-JSON bodies are stored as {body, content_type}, an empty body becomes {}, and bodies over 1,000,000 bytes are rejected with 413.
Any JSON value.
Response
Duplicate - this endpoint (or, on /v1/ingest, this ingest key) already stored a submission with the same dedup key, so the retry is answered with the first submission's id and nothing is stored or counted (ING-9, #193). The dedup key is, in order: an Idempotency-Key header; else a provider delivery id kept the same across that provider's retries - webhook-id (Standard Webhooks), svix-id, X-GitHub-Delivery, X-Shopify-Webhook-Id, X-Gitlab-Event-UUID, I-Twilio-Idempotency-Token, Linear-Delivery, Twitch-Eventsub-Message-Id, X-Atlassian-Webhook-Identifier; else the body field the endpoint's dedupe_path names, when that field holds a non-empty string or a number (HK-006); else Stripe's event id (a body with object 'event' and an evt_ id) or Slack's event_id (type 'event_callback'). The key space is the ENDPOINT's, not the workspace's: two endpoints may receive the same key. deduplicated_by names which source matched. A request that loses the unique-index race has already been counted against the monthly quota.