Work with events
Define business events and collected observations, connect their sources, and use recorded activity in workflows and scheduled evaluated attributes.
On this page
An event records a moment: an order was placed, a user signed up, or a project was created. Sarah is the contact, her order is an object with a changing status, and PurchaseCompleted is the occurrence that can start her follow-up. Define its facts, connect the producer and publish the workflow that should act on it.
Start in the event library
Open Settings, then Events. The Event library lists your event schemas with their source and attributes. Use Sources to manage the website or server connections that report observations.
Choose the producer path for the occurrence:
| Kind | Use it for |
|---|---|
| Business event | A declared action such as OrderPlaced that can trigger a workflow or be fired by a workflow step. Its payload can provide the keys used to look up the relevant contact or object. |
| Collected event | An observation reported through a configured Browser SDK or Server collection source. A binding uses the same event schema and attributes, plus its associated record scope and optional context attribute. |
Connect a collection source
- Open Sources
Choose Sources, then Connect source. Give the source a recognizable name and choose its environment and authority: Browser SDK or Server collection.
- Keep the authority clear
Browser keys collect anonymous observations. Your authenticated server links a visitor to a customer. Server keys belong on your backend and authorize activity for that source.
- Define the event
Create an event schema in the Event library and declare its fields in Attributes. Open its Collection tab, choose Bind source, and select the Source and Associated records. The event slug is its collection key; do not create a second payload definition.
One source can report several event types. For example, a product source can report both a signup observation and a first-project observation.
Declare the data you need
Use concrete names and types: an order total is a number, an order number is an identifier, and a project creator key identifies the person who created that project. A description should explain the business meaning, so generated queries have useful context.
Open an event's Attributes tab to declare the fields your producer supplies. Use Required in the event payload for values every occurrence must include. A new event field is producer-supplied; the event editor does not offer profile autofill or evaluated relationships.
On Collection, Context attribute selects a JSON object field that receives producer context. That field is excluded from producer properties. With No context, the producer sends empty context. For a ProductViewed example, productId is an event property and a declared context object can contain page and campaign information.
Collection accepts the declared shape and rejects extra properties. Native record input can instead omit unknown custom fields with a warning. Test the path your actual producer uses; successful acceptance is not proof that every intended property was stored.
Connect activity to the right person
For a business event, supply at most one explicit contactId or objectId, using the maxclicks record ID. Resolve or create that record first. A custom property containing a customer email, user ID or order ID can support a deliberate workflow lookup, but it does not establish the subject link that scheduled profile measures require.
A collection-bound event requires a subject in its configured record schema on native input as well. Collected observations follow the binding's subject and identity contract. A browser observation is not proof of an authenticated customer identity by itself. Link identity through your authenticated server before relying on person-level history.
For a product-activation journey, check projects created by the specific user. A teammate's project is not proof that this person has activated. For a post-purchase journey, look for orders belonging to the same customer and occurring after the triggering order.
Track acceptance and readiness
Use a stable eventId for one business occurrence. Retry with that ID and unchanged input after a timeout; a new ID can create another occurrence. Reusing the ID with different input is a conflict.
An accepted event may still be preparing AI-autofill fields. Only ready business events feed normal queries and downstream event delivery. The duplicate receipt describes its original acceptance; use the event status operation for current readiness. See business event status.
Inspect the right evidence
Open an event's Logs tab to inspect received history. Search by ID or payload, choose a range for the volume chart, and open a row to inspect its data. The Event library shows recent receipt activity and source configuration. Its health badge is not a delivery receipt for a particular occurrence.
Check the response from the API or SDK that submitted the event. For an automation, inspect the workflow's actual run history and the step inputs and outputs. Confirm the workflow is published, its trigger matches the intended event, and the contact lookup and condition use the right keys.
Use history without storing a second answer
An evaluated attribute can derive an answer from recorded history when requested, such as the number of a customer's orders. A scheduled evaluated attribute can publish a count, sum or latest value from one event schema on a schedule, including that schema's configured collection history. A valid publication with no matching subject history is empty, not zero. No complete publication or an expired enabled publication blocks a new decision that requests it. Check Data through and publication status; refreshing a record does not recompute the history. See scheduled evaluated attributes.
For a workflow, a query followed by an If Else step can decide whether a later action already happened. A Wait step gives the customer time before that check. Build and review the graph before publishing it.
Change a producer contract
Changing the event definition can affect producer input, workflow triggers, generated conditions and scheduled profile values. A field rename in the display does not change its stable key. A new required property can reject the next occurrence if the sender still omits it. A changed numeric bound can reject a previously valid amount.
- Prepare the new definition
Edit the event's Attributes or Collection settings. Describe why the new field or subject rule exists. Keep an example payload from your actual website or backend available for review.
- Inspect the checks
Saving runs setup checks. Open the event's Changes tab when a decision is required. Read the affected rules, invalid values and producer checks. Where a passing source sample is required, test the updated producer input before applying.
- Coordinate application
Apply the reviewed change only when the producer and downstream campaign use the same meaning. Inspect completion and any collection or workflow resumption warnings. Refused input during a pause needs a retry after reopening; a settings change does not recover requests the producer already lost.
A passing sample checks that sample against the proposed contract. It does not prove every payload from every browser, old app version or queued server job uses the new format. Check both a typical event and a missing or malformed value, and coordinate producer rollouts with the person who owns the source.
Control new collection
The source's Collection enabled setting governs all events collected through that source. An event binding has its own SDK collection enabled setting. Both need to be enabled for new SDK observations to arrive. The Collection tab shows SDK collecting or SDK paused for the configured binding.
Pausing collection does not stop native server events, workflow events or scheduled calculations over accepted history. It also does not save rejected requests for a later replay. Use a source pause when that entire connection should stop; use the binding when only one event's SDK collection should stop.
On the source, create a write key and copy the value when it is shown. Keep server collection keys on your backend. A key authorizes activity for its source; it is not a general workspace API key or permission to subscribe contacts. Replace an expiring or compromised key in your producer before revoking the working key when uninterrupted collection matters.
Diagnose a missing journey
Follow the same occurrence from input to action. Each check answers a different question:
| Check | What it establishes |
|---|---|
| Producer response | Whether that input was accepted, rejected or returned an uncertain response. |
| Occurrence identity and readiness | Which occurrence was accepted and whether preparation made it ready. |
| Subject and schema | Which contact or object the event describes, and which definition applies. |
| Published trigger and condition | Whether an active workflow should admit that occurrence. |
| Workflow run and step evidence | Whether a run started and which later actions completed or failed. |
| Email delivery evidence | Whether the resulting message reached the delivery stage; event receipt alone does not establish delivery. |
For a native event still pending, inspect current status before creating another ID. Missing AI-autofill work on an existing definition can wait for processing or credits. A failed or unresolved preparation needs its reported error investigated. An identical retry returns the original acceptance receipt, which does not advance as preparation progresses.
For collection input, verify source and binding are enabled, the write key is active, the environment matches and the payload follows the schema. Then verify identity through your authenticated server. An anonymous product view is useful activity evidence, but it is not a verified contact or email subscription.
For an event-history audience, inspect the scheduled attribute separately. Refresh now queues work; refreshing Logs does not refresh that attribute. A current record preview can differ from a campaign that captured an earlier publication. See selected data and freshness.
Frequently asked questions
Do I need separate events for browser and server input?
Use the same event schema when the business meaning is the same. Its collection binding supplies source, record scope and context handling. Native input still uses the event definition and must satisfy a configured subject scope.
Does an accepted event prove the email was sent?
No. Acceptance, readiness, workflow execution and email delivery are separate. Inspect the actual occurrence status, published workflow and run evidence.
Can I edit or replay a purchase after deleting it?
A purchase occurrence is immutable. Use a new event for a later refund. Erased occurrence identities cannot be replayed; inspect deletion completion before treating associated history as removed.
Did this article answer your question?