Events API
Read captured metadata separately from private retained content.
List events
The response contains data and next_cursor. Items contain identity, source/provider, event type when extracted, received_at, body_size/body_hash, filtered headers and signature_valid (true, false or null) with a reason when recorded.
- source_id filters a source within the authenticated organization.
- since accepts an RFC 3339 timestamp.
- onlyInvalid=true selects events with a recorded invalid signature.
- limit defaults to 50 and is bounded to 1–200. Reuse next_cursor for subsequent pages; treat it as opaque.
GET /v1/events?source_id=<source_id>&limit=50&cursor=<opaque_cursor>Search metadata and retained content
Search uses event-read permission within the selected organization. Send a literal, case-insensitive query in the POST body: surrounding whitespace is trimmed and the query must contain 1–256 UTF-8 bytes. A match can come from event metadata or available retained UTF-8 text. Content is searched as originally received, without parsing JSON/XML or decoding form values.
POST /v1/events/search
{"query":"example","limit":50,"source_id":"<optional_source_id>","cursor":"<optional_opaque_cursor>"}The limit defaults to 50 and cannot exceed 50. Each response includes data, next_cursor, scanned, body_scanned, skipped_body (expired, not_retained, unsupported), exhausted and stop_reason. A request checks at most 100 candidates, with an 8 MiB original-body byte budget and a two-second processing budget. A partial response requires another explicit request with next_cursor and the same query and source. An empty partial page does not establish that there are no matches in the remaining history.
Results contain event metadata, source_name and matched_in (metadata or content), without bodies, snippets or echoed queries. A metadata match takes precedence. A content match includes content_match_expires_at; remove that membership when retention expires and repeat the search to determine current matches. Search responses use no-store. Keep queries and match membership out of URLs, logs and shared application caches.
Inspect an event
Lists and detail can include the original delivery’s state, attempts, code, HTTP response and ambiguity. Replay jobs do not replace that original delivery. It can be absent for older or non-async captures. Capture metadata does not establish an incoming HTTP response or payment outcome.
Neither lists nor metadata detail nor Live SSE includes the retained body. The event_id is the identity used by outbound x-acklane-id; a delivery/job ID is separate.
GET /v1/events/<event_id>Read retained content
Requires event-read permission and ownership in the organization. The response contains event_id, state, body_size, body_hash, optional expires_at and replay eligibility.
available includes body_base64, including an empty string for a zero-byte body. expired and not_retained omit it. Errors and successes use Cache-Control: no-store and Vary: Authorization, Cookie, X-Org-ID.
A foreign event returns 404. A decryption failure is a server error, not a claim that the event expired. Never copy this response into shared application caches or logs.
GET /v1/events/<event_id>/content