Understanding events

An event records a business moment that can change the next customer action: a completed purchase, an abandoned cart or an expired trial. Declare the facts it carries, then use it to start a relevant journey or inform a customer calculation.

Define the event before anything sends one

For a business occurrence, open Settings → Events → Create event schema. Use a clear name such as PurchaseCompleted, then declare its custom fields in Properties: amount, currency, order ID and the status your campaign should count.

Have your producer supply a stable eventId, the occurrence time, and a maxclicks contactId or objectId when the event describes a known record. At most one explicit subject is allowed. A custom field containing an email does not replace that subject link.

For browser or server observations, create a collected-event source and definition instead. Those definitions include a source, Test or Production environment, associated record schema, and typed Properties and Context. Choose the route before asking a developer to implement the producer.

Events are added, never edited

An accepted business occurrence keeps the definition and input associated with that acceptance. It is not updated like a contact or order. If a purchase is refunded later, record the refund as a separate occurrence rather than changing the original purchase event.

Preparation can still complete after acceptance. Missing AI-autofill fields can leave an event pending until the values are prepared. Only ready events feed normal business-event queries and downstream event delivery. Erasure of a subject or schema can remove associated history; “immutable” does not mean exempt from deletion.

Make a retry safe

Use one stable eventId for one occurrence and repeat that ID with unchanged input after a network timeout. An identical retry returns the original acceptance receipt with a duplicate marker. Reusing the ID with different input is a conflict.

The original receipt is not a live status report. If it says the event was pending at acceptance, use the event status operation to learn whether preparation is now ready, failed or unresolved. Creating a different ID to retry creates a different occurrence and can create more automation.

Put an event to work

An event on its own is only a note that something happened. It becomes useful when you point automation at it:

• Start a workflow. Add an Event Fired trigger step, choose the event schema, and every matching event starts a run with the event's data in hand. A PurchaseCompleted might start a workflow that waits three days and then asks for a review.
• Call your own systems. A webhook with the Event fired trigger forwards it to a URL you control.

Choose the stream for the decision

Business events and collected observations serve different decisions. A completed purchase can start a journey immediately after it is ready. Product views or feature usage can form a typed collected stream and feed a recurring measure of interest or activity.

A browser source collects anonymous observations. Your authenticated server controls the link to a contact. That link does not grant email consent, and saving a collection definition does not publish a workflow for it.

A computed customer attribute can count observations over a window and refresh on a cadence. It may be more useful to act when the resulting measure crosses a threshold than to send a message for each observation. See computed attributes.

Record or event?

Ask whether you are describing a thing or a moment. If you would ever change it later, it is a record. If it only makes sense as a one-time signal, it is an event.

The two work together. A PurchaseCompleted arrives, a workflow catches it, looks up the matching contact, and sends the thank-you.

Check what actually arrived

Inspect the event library and Received events history for a business schema, then check the individual acceptance/readiness status when diagnosing a missing event. Live in the library means recent activity and a configured trigger, not proof that this occurrence delivered an email.

Next inspect the published trigger, its condition and the workflow run. For a computed attribute, check its published Data through timestamp: refreshing the event list does not refresh the calculation.

Next

Connecting records, or the events reference for sending them from your own code.