Since Notifuse 18, your application can send custom events to Notifuse: an order, a subscription, a booked demo, a started trial, anything your contacts do outside of email. Each event goes on the contact's timeline. Mark one as a goal, with a type and a value, and your segments and automations can use it to find customers who spent more than 500 in the last 30 days, buyers with three orders or more, or customers who haven't bought anything in two months.

Custom events

Your backend sends an event to customEvents.upsert with the contact's email, an event name and an external_id, the ID the thing already has in your system, such as an order number or a payment ID:

{"workspace_id": "your_workspace", "email": "ana@example.com", "event_name": "order.completed", "external_id": "order_1042", "goal_type": "purchase", "goal_value": 89.90, "properties": {"items": 3, "category": "shoes"}}

Event names use up to 100 lowercase letters, numbers, underscores, dots, hyphens and slashes, so the topics your other tools already send, such as payment.succeeded or orders/paid, pass as they are. properties keeps any JSON object you want with the event. occurred_at says when it happened, and defaults to now. If the address is new, the upsert creates the contact.

One per ID

An event name and an external ID make one event. Send the same pair again with a later occurred_at and Notifuse updates the stored event instead of creating a duplicate. Fields you leave out keep their stored value, and the response is the event as stored. A send that isn't newer is ignored, so a late retry or a webhook that arrives out of order can't overwrite a newer state. Set deleted_at to take an event out of goal totals, and set it back to null to restore it.

Backfills

customEvents.import takes up to 50 events per call, in one transaction: if one event is invalid, none is saved. It doesn't create contacts, so import your contacts first. customEvents.get and customEvents.list read them back: one by its ID, a contact's events, or every event with a given name.

Goals

goal_type takes one of seven values: purchase, subscription, lead, signup, booking, trial and other. A purchase or a subscription needs a goal_value, the amount. For the other types it's optional.

A value can be negative: send a refund as its own event with a negative amount, and the customer's total goes down. goal_name is an optional label, such as pro_plan, to tell apart goals of the same type.

Website goals

With Web Analytics, added in Notifuse 38, the goals your site tracks are stored the same way. When a visitor you identified reaches a goal, it arrives as a custom event of that contact, named after the goal, with the type and the value your site gave it. It then works like the events your backend sends.

Timeline

Every event shows in the contact's activity, under its name, with its goal name and value. An update adds a new entry that says the event was updated.

Goal segments

In the segment builder, add a Goal condition. You pick:

  • Has or has not. "Has not" also matches contacts with no event at all.

  • A goal type, or all types at once.

  • A goal name and an event name, both optional, if you only want to count one plan or one kind of event.

  • An aggregate of the values: sum, count, average, minimum or maximum.

  • A comparison: greater than or equal, less than or equal, equal to, or between two values.

  • A timeframe: anytime, in the last N days, in a date range, before or after a date.

  • Property filters on the event's own properties, as text, number or date, to keep for instance only orders whose category is shoes.

Notifuse 37 added negation and the name and property filters. You can combine the condition with your other conditions (contact fields, lists, email opens and clicks, website visits) using AND and OR. Through the API, the same condition is a leaf with "source": "custom_events_goals", with negate, goal_name, event_name and filters.

Membership follows the events: when an event is created, updated or deleted, Notifuse checks its contact again shortly after. A segment that looks at the last N days is also rebuilt every day at 5:00 in its timezone, so contacts whose events drift out of the window leave it.

Automations

A custom event can start an automation: pick Custom event as the trigger and type the event name. It starts on a new event, not when one is updated, deleted or restored: send a new external_id for a new occurrence. Since Notifuse 44, the automation's emails read the event that started the journey as {{ trigger_event }}, such as {{ trigger_event.properties.items }}. Goal conditions also work in a trigger's entry conditions and in filter nodes. Webhook subscriptions can receive custom_event.created, custom_event.updated and custom_event.deleted, filtered by goal type or event name. Website goals aren't sent to them.

Four segments

VIP customers

Has purchase, sum, greater than or equal to 800, anytime, and has purchase, count, greater than or equal to 3. This catches customers who spent a lot across several orders, so a single big basket isn't enough.

Recent big spenders

Has purchase, sum, greater than or equal to 500, in the last 30 days. Refunds sent as negative values come off the total, so a returned order doesn't keep someone in.

Lapsed customers

Has purchase, count, greater than or equal to 1, anytime, and has not purchase, count, greater than or equal to 1, in the last 60 days. These customers bought before and then stopped, so send them a comeback offer. The daily rebuild brings them in once their last order is 60 days old.

Active trials

Your app sends trial.started with the goal type trial. Has trial, count, greater than or equal to 1, in the last 14 days, and has not subscription, count, greater than or equal to 1, anytime: everyone in their first two weeks who hasn't paid yet.

Old fields

Custom events replace three contact fields: lifetime_value, orders_count and last_order_at. The upgrade to Notifuse 18 removes them, with the segments built on them: rebuild those with goal conditions.

Not yet

  • Events without a goal stay out of segments. They show on the timeline and can start an automation, but the segment builder only counts events with a goal type. Give them the type other if none fits.

  • Property filters only read the first level of properties, so they can't reach a key inside a nested object.

  • A goal value is a plain number with no currency, so amounts in different currencies add up as they are. Convert them before you send.

  • Templates can't read a contact's events or totals. Only an automation's emails read one event, the one that started the journey.

  • There's no Zapier step. Zaps can't send custom events yet, so call the API from your backend.

Getting started

If you self-host and upgrade from a version before 18, check which segments use the old fields first. Send events from your backend with an API key that can write contacts: customEvents.upsert as they happen, customEvents.import to load your history. Then create a segment with a Goal condition, or an automation triggered by one of your events. The custom events documentation lists the fields and goal types, and the contacts documentation covers the segment builder.