Custom events let you connect real-world actions — purchases, bookings, app interactions, CRM updates — to your Marketing Automation flows. When a custom event fires for a profile, it can trigger a flow, personalise email content with event data, branch the journey, or hold a profile until a specific action happens.
This article covers the full workflow: understanding custom event types, using them to start a flow, personalising email content with event data, and using custom events inside Check Profile and Wait for Event nodes.
In this article
Prerequisites — What you need before you start
Before you can use a custom event in a Marketing Automation flow, the event must exist in your Apsis One data model. Here's the setup chain:
Step | Where | What to do |
1 | Data Model (Settings → Data Model) | Create the custom event — define its name, type (Transaction, Conversion, or Signal), and data fields. See About Custom Events. |
2 | Web tracking or API | Implement the code that sends the event to Apsis One — either via the web tracking script on your site, or via the API from your backend/CRM. See Web Tracking: Custom Events or API: Custom Events. |
3 | Marketing Automation | Select the custom event in your flow's Listen node (or Check Profile / Wait for Event node). This is what this article covers. |
💡 Good to know: f you don't see your custom event in the Listen node dropdown, it hasn't been created in the Data Model yet. Custom events appear in the dropdown once they're defined in the Data Model, even before any data has been collected.
Understanding custom event types
When you create a custom event in the Data Model, you choose one of three types. The type determines how the event is categorised and which data fields are available — but all three work the same way in Marketing Automation.
Type | What it represents | Typical data fields | Example events |
Transaction | A completed exchange of value — usually a purchase or order | Order ID, product name, price, quantity, currency, category | "Purchase completed", "Subscription renewed", "Booking confirmed" |
Conversion | A goal completion — a profile reaching a desired outcome | Conversion type, value, source, campaign ID | "Trial started", "Demo requested", "Whitepaper downloaded", "Lead qualified" |
Signal | A meaningful interaction that doesn't necessarily involve a transaction or conversion | Any custom fields you define | "Survey completed", "Poll answered", "Loyalty tier changed", "Preference updated" |
💡 Tip — Which type should I choose? If you're unsure, ask yourself: does the event involve money changing hands (Transaction), a measurable goal being reached (Conversion), or simply an important action worth tracking (Signal)? If it's still unclear, Signal is the most flexible type — it accepts any data fields you define.
Use a custom event to start a flow (Listen node)
The most common use of custom events in Marketing Automation is as a flow trigger — the event fires, and the profile enters the flow.
Step-by-step
Create a Marketing Automation flow (or open an existing one). Click on the Listen node to open its settings.
Select Events as the data source.
Choose Custom Events from the event categories.
Select the custom event type: Transactions, Conversions, or Signals.
Select the specific custom event from the dropdown. This lists all custom events of the selected type that have been created in your Data Model.
(Optional) Add a Match filter to narrow the trigger to a specific field value. For example, only trigger the flow when the product category equals "Premium".
Expand the Match section, select the event data field to match on (e.g.
category), choose a match type (e.g. "equals"), and enter the value.💡 Tip: If you skip the Match filter, the flow will trigger for every instance of the custom event — regardless of the data it carries. Use Match when you only want the flow to start for specific scenarios (e.g. only high-value purchases, only a certain product category, only bookings for a specific destination).
(Optional) Set frequency and time frame conditions. You can require the event to have been fired a certain number of times (e.g. "at least 3 times") and optionally within a specific time frame (e.g. "within the last 30 days") before the flow starts.
💡 Good to know: Frequency conditions are most useful for flows that should only activate after repeated behaviour — e.g. triggering a loyalty reward after 5 purchases, or flagging a support issue after 3 failed login attempts.
(Optional) Add a Segment filter. Expand Advanced options and add a segment to further restrict which profiles can enter the flow. Only profiles who trigger the event and are members of the segment will enter.
Personalise email content with custom event data
When a custom event starts the flow, the event's data fields become available for personalisation in Email nodes within that flow. This means you can dynamically insert event-specific data — like a product name, booking destination, order total, or departure time — directly into the email your profile receives.
💡 Good to know: Event data personalisation is available in any Email node within the flow, not just the first one. The data from the triggering event travels with the profile through the entire flow. This also works with standard events (not just custom events) — any event selected in the Listen node makes its data fields available in Email nodes.
Step-by-step: Insert event data into an email
Make sure your Listen node is configured with the custom event (steps above).
Add an Email node to your flow and click Create new email to open the email editor.
In the email editor, click inside a text element where you want to insert the event data.
In the inline text editor toolbar, click Events.
A dropdown appears showing all data fields from the custom event selected in your Listen node. Choose the field you want to insert — e.g.
departure_time,product_name,order_total.The data tag is inserted into your email. It will be replaced with the actual event data when the email is sent to each profile.
Click Finish and then Save as draft or Ready to Send to return to the canvas. You'll see a preview of the email in the node — the data tags will show as placeholder text in the preview.
⚠️ Important: Event data personalisation tags work just like regular data tags (personalisation tags for attributes). If the event data field is empty for a specific profile's event, the tag will render as blank in the email. Consider a fallback or designing your email to handle missing values gracefully.
What event data can I use?
The available fields depend on how you defined the custom event in the Data Model. Every field you added to the event schema is available for personalisation. Common examples:
Event type | Example fields available in email |
Transaction (e.g. "Purchase completed") | Product name, price, quantity, order ID, currency, category |
Conversion (e.g. "Demo requested") | Demo type, preferred date, company size, source page |
Signal (e.g. "Booking confirmed") | Departure time, destination, booking reference, passenger count |
Use custom events in Check Profile and Wait for Event nodes
Custom events aren't limited to the Listen node. You can also use them mid-flow to branch the journey or hold a profile until a specific action occurs.
Check Profile node — Branch based on past custom events
Use a Check Profile node to evaluate whether a profile has (or hasn't) fired a specific custom event — and route them accordingly.
Example: After sending a promotional email, wait 5 days, then check if the profile has a "Purchase completed" event. If yes → send a thank-you email. If no → send a reminder with a discount code.
Add a Check Profile node to your flow.
Select Events → Custom Events → choose the event type and specific event.
Optionally add a Match filter and frequency/time frame conditions — e.g. "Purchase completed at least 1 time within the last 5 days".
Connect the Yes and No outputs to different paths.
Wait for Event node — Hold until the event fires
Use a Wait for Event node to pause a profile's journey until a specific custom event fires — or until a timeout period expires.
Example: After sending a booking confirmation, hold the profile for up to 7 days waiting for a "Payment received" event. If the event fires → continue to confirmation flow. If it times out → send a payment reminder.
Add a Wait for Event node to your flow.
Select Events → Custom Events → choose the event type and specific event.
Optionally add a Match filter to wait for a specific value.
Set the timeout — how long the node should wait before releasing the profile down the "not matched" path.
Connect both outputs: Event matched and Timed out.
💡 Tip: The Wait for Event node is one of the most powerful nodes for custom event workflows. It lets you build flows that respond to real-world actions happening outside Apsis One — like payments, deliveries, app logins, or CRM status changes — without requiring you to know exactly when they'll happen.
Use cases
Post-purchase follow-up (Transaction event)
Trigger: Listen node → Custom Events → Transactions → "Purchase completed"
Flow: Listen → Time (1 day) → Email ("Thanks for your order! Your [product_name] is on its way.") → Time (7 days) → Email ("How's your [product_name]? Leave a review.") → End Flow
Personalisation: Product name, order ID, and price pulled from the event data into both emails.
Why it works: Combines real-time triggering with event data personalisation for a fully automated, product-specific follow-up sequence.
Booking confirmation with payment wait (Signal event + Wait for Event)
Trigger: Listen node → Custom Events → Signals → "Booking confirmed"
Flow: Listen → Email ("Booking confirmed! Departure: [departure_time], Destination: [destination]") → Wait for Event ("Payment received", 3-day timeout) → Payment received: Email ("Payment received — you're all set!") → End Flow / Timed out: SMS ("Your payment is still pending") → Time (2 days) → Email ("Final reminder: complete your payment") → End Flow
Why it works: The Wait for Event node bridges two separate real-world actions (booking and payment) within a single flow, with graceful fallback for incomplete payments.
Lead scoring and sales handoff (Conversion event + Check Profile)
Trigger: Listen node → Custom Events → Conversions → "Demo requested"
Flow: Listen → Time (2 days) → Check Profile → Event: "Page view" on pricing page at least 2 times within 2 days → Yes: Notification node (alert sales: "Hot lead — visited pricing page after demo request") → Update Profile (add tag "Sales qualified") → End Flow / No: Email ("Here's a recap of what we covered in the demo") → End Flow
Why it works: Combines a custom event trigger with standard event evaluation and internal notifications — bridging marketing and sales seamlessly.
Loyalty tier upgrade with conditional branching (Transaction event + Match + Frequency)
Trigger: Listen node → Custom Events → Transactions → "Purchase completed" → Match: none (all purchases) → Frequency: at least 5 times within 365 days
Flow: Listen → Check Profile → Attribute: "Loyalty tier" equals "Gold" → Yes: Email ("You're already Gold — thank you!") → End Flow / No: Update Profile (set "Loyalty tier" to "Gold") → Email ("Congratulations! You've reached Gold status 🎉") → Notification node (alert CRM team) → End Flow
Why it works: Uses frequency conditions to trigger only after 5 purchases in a year, then checks current status to avoid redundant upgrades. Combines event frequency, attribute checking, profile updating, and internal notifications in one flow.
Technical deep dive
How custom events are processed in real time
When a custom event is sent to Apsis One (via web tracking or API), it is processed immediately. If a Marketing Automation flow has a Listen node configured for that event, any matching profile enters the flow within seconds of the event firing. There is no batch delay — custom event triggers are real-time.
Event data lifecycle in a flow
The data carried by the triggering event stays available throughout the entire flow journey for that profile. This means:
An Email node at position 2 in the flow has access to the same event data as an Email node at position 5.
If the flow includes Time nodes with multi-day delays, the event data is still available when the profile eventually reaches a downstream Email node.
Each profile's event data is independent — if two profiles enter the flow from different event instances, each sees their own event data in emails.
Event versions
Custom events can have multiple versions if you change the event schema in the Data Model (e.g. adding or removing fields). When you select a custom event in a node, you may be prompted to choose a version. Key points:
Always use the latest version unless you have a specific reason to target an older schema.
If you update an event's schema, existing flows that reference the old version will continue to work — but they won't see the new fields until you update the node to the latest version.
Each version has a unique version ID, visible in the Data Model.
Custom events vs. standard events
| Custom events | Standard events |
Defined by | You — in the Data Model | Apsis One — built into the platform |
Data fields | You define them (flexible) | Fixed per event type (e.g. email opens always include activity ID, timestamp) |
Source | Your website (web tracking), your app, or your backend/CRM (API) | Apsis One platform (email sends, form submissions, page views, subscription changes) |
Real-time trigger | Yes | Yes |
Email personalisation | Yes — all custom fields available | Yes — standard event fields available |
Typical use | External actions: purchases, bookings, app events, CRM changes | Platform actions: email engagement, form submissions, subscription changes |
API identifiers and permission settings
When sending custom events via the API, the event is associated with a profile using an identifier (email, mobile, or CRM ID). The Data Model includes permission settings that control which identifiers can be used by external systems to read or write profile data. If your API integration can't send events, check the identifier permissions under the custom event's settings in the Data Model.
Troubleshooting
Problem | Likely cause | Solution |
Custom event doesn't appear in the Listen node dropdown | The event hasn't been created in the Data Model, or you're looking under the wrong type (Transaction/Conversion/Signal) | Go to Settings → Data Model and verify the event exists. Check which type it was created under. If it's new, it may take a moment to appear. |
Flow is active but no profiles are entering | The event isn't being sent from your website/app/API, or a Match filter is too restrictive | Verify that events are actually being sent — check your web tracking or API logs. If events are firing, temporarily remove the Match filter to see if profiles enter. Also check Flow Settings → Subscriptions. |
Event data personalisation shows blank in the email | The event data field is empty for that specific event instance, or the wrong event version is selected | Check the event data being sent — is the field populated? Verify the event version in the Listen node matches the version your system is sending. Consider a fallback in your email design. |
Event data fields don't appear in the email editor | The Listen node isn't configured with a custom event, or the Email node was created before the Listen node was set up, or the version ID is not correct. | Configure the Listen node with the custom event first, then create the email. The editor pulls available fields from the Listen node's event configuration. |
Profile enters the flow multiple times from the same event type | Entry Limit is set to Unlimited or more than 1, and the event fires multiple times | Review Flow Settings → Entry Limit. If you only want one journey per profile, set it to 1. If multiple entries are intentional (e.g. per purchase), this is expected behaviour. |
Wait for Event node never triggers | The event isn't firing, the Match filter doesn't match the actual event data, or the event version doesn't match | Check API/web tracking to verify the event is being sent. Verify the Match filter values exactly match what's being sent (case-sensitive). Check the event version. |
API can't send events — permission error | Identifier permissions in the Data Model are restricting write access | Go to the custom event settings in the Data Model and check the identifier permissions. Ensure the identifier your API uses (email, mobile, or CRM ID) has write permission enabled. |
What's next?
About Custom Events — How to create and configure custom events in the Data Model.
Web Tracking: Custom Events — Implement custom event tracking on your website.
API: Custom Events — Send custom events via the Apsis One API.
Profile Data in Marketing Automation Nodes — How to use all types of profile data (attributes, tags, events, segments) in your flows.
Wait for Event Node — Full reference for the Wait for Event node.
Check Profile Node — Full reference for branching logic with events and other data types.