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 defines the events your backend, workflows, integrations and collection sources report. Each event has one schema and key. A browser or server collection binding uses that schema's attributes, rather than maintaining a second event definition. The producer path changes authorization and identity; the shared definition gives campaigns one business meaning.
A thing and something that happened to it
An Order object holds the current order: its status can change from placed to refunded. A PurchaseCompleted event records the earlier purchase, and a later RefundIssued event records the refund. Updating the object does not rewrite either occurrence.
The same distinction works for software: an Account object holds today's plan; a PlanUpgraded event records when it changed. Use the object for current context and the event for the moment a journey should react to.
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, create the same event schema, then configure its Collection binding. The binding adds a source, associated record scope and optional context field. Do not create a duplicate PurchaseCompleted schema merely to accept it from another producer path.
Add the fields it carries
Open a business event schema's Attributes 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 Logs 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 collection 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.
Open the event's Collection tab and choose Bind source. Select the Source and Associated records. Browser sources associate with a contact schema; server sources can associate with contacts or objects. Each event has one collection binding. The event key is its existing schema slug, and its payload contract comes from Attributes.
Context attribute optionally selects a JSON object attribute on the event. Producer context fills that attribute, which is excluded from producer properties. With No context, the producer must send empty context. For a product view, keep productId in event properties and route page/campaign information into a declared context JSON attribute.
Required event fields use Required in the event payload. New event attributes are producer-supplied; their editor does not offer profile autofill or evaluated relationships. Collection validates the declared property shape and rejects undeclared properties. Native record input can report omitted unknown fields as warnings, so test the actual producer path rather than assuming both tolerate an extra property.
Recorded occurrences cannot be backfilled. Adding a required field after this event type has recorded history is blocked, even if a new producer sample includes it. Keep the field optional or create a new event type for the new required contract.
Saving a definition or binding change runs setup checks. Changes to fields used by workflows or scheduled evaluations need their dependents validated. A producer-facing contract change can require a passing source sample before application. Inspect Changes, coordinate the new producer payload, and review any collection pause or retry requirement before switching.
SDK collection enabled controls the binding. Pausing it, or pausing its source, stops SDK collection; native server events, workflow events and calculations continue. Paused intake does not queue rejected requests for later replay. Existing accepted history is separate from the choice to accept new observations.
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 event schema 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.
For collection input, verify the binding's associated schema and resolved subject as well as the trigger condition. Review and publish the workflow. Receiving observations before publication does not request a backfill of runs from 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
Create an Evaluated attribute on the destination contact or object schema. Describe a count, sum or latest value from this event schema, plus its filter, rolling window and cadence. Review the generated schedule and destination before saving. The profile owns the result; the event supplies the history.
For business event sources, only ready events within the occurrence-time window and explicitly linked to that profile qualify. A valid publication with no qualifying history gives an empty result rather than zero. No complete publication, or an expired enabled publication, blocks a new decision that requests it. Check Data through and the published status before using the value in an audience. The complete setup and freshness rules are in Scheduled evaluated 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.