Events
Events bring customer behavior into your decisions: an order completed, a trial started, or a visitor viewed a product. The useful contract includes what happened, when it happened, which record it describes, and which facts the campaign needs.
Settings → Events brings together two sources of activity. Business event schemas carry typed records from your backend, workflows or integrations. Collected events define the observations a browser or server source can send. Both can support automation and computed customer attributes, but their setup and identity rules differ.
Define the event
Choose Create event schema for a business event such as PurchaseCompleted. Give it a name, plural name, slug and description. The slug is its stable API reference. Define one schema for one business meaning, and use properties for variations such as plan, currency or purchase channel.
For website or server collection, follow Collected events below. A collection definition is not a business event schema with a different name: it has a source, environment, subject type and versioned payload contract.
Add the fields it carries
Open a business event schema's Properties tab and add the attributes the downstream decision needs. For an order, that may be order number, amount, currency and status. Declare each custom field before sending it; unknown custom fields are omitted with a warning.
The event also has platform fields:
| Field | Meaning |
|---|---|
id | maxclicks' identifier for the accepted event |
eventId | Your stable identifier for this occurrence, used for retry detection |
occurredAt | When the business action happened |
receivedAt | When maxclicks accepted it |
readyAt | When preparation completed; empty while it is not ready |
contactId or objectId | An explicit subject in the same workspace; supply at most one |
readinessState | Whether the event is ready for downstream use |
definitionRevision | The definition accepted for this occurrence |
A subject ID is a maxclicks record ID, not an email address, your application's user ID, or an object's external ID. Resolve or create that record first. You can still store external identifiers as custom properties, but that alone does not establish the subject link needed by a profile calculation.
Use occurredAt for behavioral windows. Omitting it uses the acceptance time. The business Events API accepts occurrence times up to 366 days in the past or five minutes in the future, and limits a single input to 256 KiB. See the Events API for the full wire format and batch behavior.
Fire it
Business events can arrive through the Events API, an integration, or a workflow's Fire Event step. There is no CSV event import. A new occurrence is immutable; an update to your source record does not rewrite the old event.
Acceptance and readiness are separate. An event whose missing fields require AI autofill can be accepted durably while preparation continues in the background. Only ready events are exposed to normal business-event reads and generated queries, and only readiness starts their downstream event delivery.
| Readiness | What it means for your campaign |
|---|---|
pending | Accepted, still preparing; it is not yet a trigger-ready event |
ready | Prepared and available for queries and downstream event delivery |
failed | Preparation ended with an error; inspect the failure before relying on the occurrence |
outcome_unknown | A preparation outcome could not be established safely; reconcile the accepted occurrence rather than submitting a new occurrence ID |
Erasure can remove the event record and retain an erased acceptance receipt. A later status read may therefore report no event, while a replay of its occurrence identity is rejected.
A pending event can wait for available credits or processing capacity. An acceptance response does not prove that a workflow has run or that an email was sent.
Make retries safe
Set eventId once per occurrence and reuse it for retries of that same input. A network retry of order-184-paid should still mean the same purchase, with the same subject, properties and explicitly supplied occurrence time.
maxclicks returns the original acceptance receipt for a duplicate and marks it as a duplicate. It rejects reuse of that ID with different input. A retry does not revise the accepted definition or replace its data.
The receipt's readiness describes the moment of acceptance. To learn what happened afterward, use the event status operation in the Events API. A newly generated event ID means a new occurrence and can cause new automation.
Watch them arrive
Open a business event's Received events tab. Choose a date range and search by ID or payload; the histogram and paginated rows help you locate actual incoming activity. The library shows receipt volume, last receipt and declared properties.
The library's health badges describe source activity and configuration:
- No events means no recorded receipt for the schema.
- Archiving only means activity is arriving without a published workflow or live webhook using the event as a trigger.
- Live means activity is arriving and a trigger is configured.
- Silent means the source has received events before but has been quiet long enough to flag it.
These badges are not a per-occurrence delivery receipt. For a missing journey, trace the event ID through acceptance/readiness, then inspect the workflow run. Check the selected schema, subject, trigger condition and published workflow version.
Collected events
Use collected events for a typed activity stream from a site or server, such as product views or feature usage. In Settings → Events → Sources, choose Connect source and set:
| Control | Decision |
|---|---|
| Name | A source your team can recognize, such as Storefront |
| Connection | Browser SDK for anonymous browser observations, or Server API for backend-authorized activity |
| Environment | Test or Production; the creation default is Test |
| Collection enabled | Whether the source accepts incoming observations |
Connection type and environment are fixed after creation. Pausing a source rejects incoming requests; it does not collect them into a queue for later.
Create a collected-event definition from the event library or source. Set its display name, stable Event key, Source, and Associated records. Browser sources associate with a contact schema. Server sources can associate with contacts or objects. The key, source and associated-record choice are fixed after creation.
Define two object-shaped JSON schemas:
- Properties describes the event itself, including required and nested values.
- Context describes allowed page, campaign or other surrounding information.
Use the schema editor's sample validation before connecting the producer. Saving an edit creates a new definition revision. Published workflows keep the revision they were published against until you republish them, so coordinate producer changes and workflow changes.
Connect the source and establish identity
On the source, use Create write key, set its lifetime, and copy the new value before leaving: it is shown only once. A source key can send every enabled event defined for that source. Keys show Active, Expired or Revoked. Install a replacement before revoking a working key when collection should continue.
Keep server keys on your backend. Browser credentials authorize anonymous observations; they do not authorize a visitor to choose a customer identity. Your authenticated server establishes the connection between an anonymous identity and an existing contact. See the identity operation in the Events API for the server-side contract.
A collected observation does not itself subscribe a contact to email. Keep identity resolution, collection permission and communication consent as explicit decisions in your implementation.
Start a workflow from it
Add an Event Fired trigger and choose the business event or collected-event definition it should use. For a business event, a generated condition can narrow the trigger, for example “Only completed purchases over 100 EUR.” Review the actual currency and status fields so the condition means what your team intends.
A collected-event trigger uses its selected definition revision and associated subject. Review its filters and publish the workflow. Receiving observations before the workflow is published is not a request to backfill runs for the earlier history.
Later steps use the trigger's declared output. Inspect Reads and the email's Data tab before referring to the event's values in Liquid or Adaptyle. Business events can also drive webhooks; inspect the webhook's condition and delivery results separately.
Turn event history into customer context
Open the event's Computed attributes tab to turn its history into a count, sum or latest value on a contact or object profile. Describe the measure, source, filter, rolling window and cadence; review the definition before creating it.
For business event sources, only ready events within the occurrence-time window and explicitly linked to that profile qualify. No qualifying history gives an empty result rather than zero. Check Data through and the published status before using the value in an audience. The complete setup and freshness rules are in Computed attributes.
What you cannot undo
You cannot edit a business event occurrence into a different fact. Send a new event for a subsequent business action, such as a refund, with its own occurrence ID.
Deleting an event schema or erasing a linked record uses a deletion process that can also remove associated event history and derived data. Deletion is permanent, can be blocked by dependencies, and may continue after the initial request. An erased occurrence cannot be replayed with its previous ID. Review the operation's completion before treating cleanup as finished.