Skip to content
cascadehook.docs
API referenceEvents

Publish an event

Maximum 256 KiB envelope; exactly type and data. Same key/exact bytes within 24 hours returns the original receipt without fan-out again. Different bytes return 409 idempotency_conflict. Keys remain project-wide regardless of dev/live label; use only agreed test data.

POST
/v1/events

Maximum 256 KiB envelope; exactly type and data. Same key/exact bytes within 24 hours returns the original receipt without fan-out again. Different bytes return 409 idempotency_conflict. Keys remain project-wide regardless of dev/live label; use only agreed test data.

Authorization

projectAPIKey
headerAuthorizationBearer <ch_dev_ or ch_live_ project API key>

Read CASCADEHOOK_API_KEY from the local environment. Never print keys or headers. Scope is the project selected when the key was created.

Header Parameters

Idempotency-Key*string

One key per logical event. Reuse with the EXACT serialized bytes on retry, within 24 hours. Whitespace changes also cause idempotency_conflict.

Match^[!-~]+$
Length1 <= length <= 255

Request Body

application/json
  1. body

Exactly type and data; duplicate envelope keys are rejected. Entire serialized body maximum 262144 bytes. Retries must preserve exact bytes and Idempotency-Key.

type*EventType
Match^[a-z0-9][a-z0-9_.-]{2,127}$
Length3 <= length <= 128
data*unknown

Any JSON value, including null.

Response Body

Acceptance only, not confirmed delivery. Zero delivery_count means no matching ready endpoint. Publish a NEW event after fixing setup.

application/json
  1. response
id*string
Formatuuid
type*EventType
Match^[a-z0-9][a-z0-9_.-]{2,127}$
Length3 <= length <= 128
created_at*string
Formatdate-time
delivery_count*integer
Range0 <= value
Example Request
curl -X POST 'https://api.cascadehook.com/v1/events' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "type": "invoice.paid",  "data": {    "invoice_id": "inv_test_1024"  }}'
Example Response
{  "id": "01900000-0000-7000-8000-000000000002",  "type": "invoice.paid",  "created_at": "2026-01-01T00:00:00Z",  "delivery_count": 1}

List event summaries GET

Returns newest-first retained data. Unknown or repeated query parameters are rejected. Follow next_cursor until null; preserve filters. Omit cursor on the first page.

Read current delivery state GET

succeeded confirms receiver acknowledgement, not downstream business completion. pending/leased are not terminal. Inspect attempts and terminal_reason for failures.