Submissions
A submission is the body as it arrived, stored before anything reshapes it, together with the request it came in: the method, the headers, the query string, the content type and the source IP. Credentials are never kept:Authorization, Cookie, and any header or query parameter named like a key, token, secret, password or session is stored as [redacted]. Two kinds of body are stored in a normalised form: a multipart form keeps its fields, with each file as a {filename, type, size} descriptor and its bytes discarded, and a text body that is not JSON is kept as { "body": "…", "content_type": "…" }.
The 201 answer to a request names its submission as submission_id. Each submission counts once against your monthly event quota, however many records it makes. A refused request, or a duplicate Hookie recognised, does not count.
A submission’s routing status tells “nothing matched” apart from “never arrived”. Filter by it on the Observability tab, under Submissions:
Errors tab
Some events are received and kept but never reach a dataset. A project’s Errors tab lists them, newest first. There are two kinds:- Filtered. The endpoint’s criteria rejected the payload. For example, an endpoint that accepts only
type = order.createdreceives anorder.cancelled. The sender still gets201, withrouted: [],records: 0andfiltered: true. The Reason column names the criterion the payload did not meet. - Routing failed. The event was stored, but its records could not be written. Hookie keeps retrying it in the background, and it leaves this list once it is routed.
GET /admin/api/projects/{project_id}/errors?kind=all|filtered|routing_failed&limit=25&offset=0 returns { rows, total, limit, offset }, and GET /admin/api/projects/{project_id}/errors/{id} returns one event with its whole payload. A connected agent can use list_project_errors, and the CLI has hookie errors list.
Records
A record is one routed event in a dataset: a JSON object holding the mapped fields, or the whole payload when nothing mapped it. A payload that is not an object, such as a bare array, is stored as{ "value": … }. Every record has an id, the time it was received and where it came from, listed as _id, _received_at and _source beside its fields.
One submission can make no record, one, or several, because every rule that matches writes its own. On an ingest key with no dataset in the URL, an event no rule matches still makes one: the key’s default dataset gets the whole payload. The same holds for a cron or WebSocket trigger with no dataset, whose unmatched events go to the default dataset. Records, not submissions, are what fan out. Each new record is:
- delivered to every enabled destination in its project whose dataset filter admits it;
- published on the project’s live stream;
- offered to the project’s AI triggers and workflows.
Hookie-Event-Id on every delivery of it.
Records also come from cron and WebSocket triggers, database sources, a workflow’s emit_event step and an AI trigger’s output. They fan out the same way, except that a record a workflow or an AI trigger wrote never starts a workflow, and an AI trigger’s output never fires an AI trigger, so neither can loop. Events from cron and WebSocket triggers and database sources count against the monthly event quota like ingested ones.
Datasets
A dataset is a name that records are filed under, such asorders. There is no step to create one: it appears on the project’s Datasets tab the moment the first record is routed into it, whether from an endpoint, an ingest key’s path, a rule, a trigger or a workflow. A dataset name starts with a letter and uses only letters, digits and underscores, up to 63 characters. A dataset belongs to its project: an orders dataset in two projects is two datasets.
The Datasets tab lists each dataset with its number of records and when the last one arrived. Open one to page through its records, 25, 50 or 100 at a time, and save views that pick the fields to show, rename them, and set how the records sort. A view can also be shared with your customers in the portal. The eye icon on a row (Open record) shows a record whole, with the Request it arrived in. Export CSV and Export XLSX export the whole dataset, not just the page; an XLSX file stops at a spreadsheet’s 1,048,575 rows, and a CSV has no limit.
Outside the console, read records with:
GET /admin/api/projects/{project_id}/datasets/{name}, which pages by cursor (see Reading a whole dataset);search/events, for filtered searches with a time window;- the
query_recordsandget_recordtools of a connected agent; - the read-only Data API, for tools outside Hookie.
Retention
Event data is kept for your plan’s retention window, then deleted automatically:
The window covers records, submissions, deliveries and their attempts, held deliveries, the refused-request log, workflow runs, AI trigger runs and the AI call log. A cleanup runs every five minutes and deletes what has aged past the window, counted from when it was received or created. A delivery that is still queued, retrying or paused is kept until it finishes. The audit log has its own, longer window: the longer of your plan’s retention and one year.
After a downgrade to a plan with a shorter window, your previous plan’s window still applies for 7 days. After that, the next cleanup deletes data older than the new plan’s window. Home shows the date until then. See Retention after a downgrade. A delivery whose record has been pruned cannot be replayed.
To delete data sooner, one record or a whole dataset, or to export everything, see Delete, export and close.