v18.0

# Notifuse v18.0 Release Notes

**Release Date:** November 29, 2025

## Custom Events Tracking System

This release introduces a powerful custom events tracking system that enables you to track user behavior and conversion goals, then leverage that data for advanced segmentation.

### New Features

#### Custom Events API

Track user behavior and conversion goals with the new Custom Events API:

- **`POST /api/customEvent.upsert`** - Create or update a single event
- **`POST /api/customEvent.import`** - Batch import up to 50 events
- **`GET /api/customEvent.get`** - Retrieve event by workspace, event name, and external ID
- **`GET /api/customEvent.list`** - List events by email or event name

Supported goal types: `purchase`, `subscription`, `lead`, `signup`, `booking`, `trial`, `other`

<img width="1717" height="799" alt="Screenshot 2025-11-29 at 18 39 05" src="https://github.com/user-attachments/assets/263592bf-4a81-4cb7-aee4-1fde88c4af54" />


#### Segmentation with Custom Events Goals

Create targeted segments based on what your contacts have achieved. Track and segment by these goal types:

- **Purchase** - Track revenue and buying behavior. Segment contacts who spent over $500 in the last 30 days, or customers with more than 3 orders.
- **Subscription** - Monitor recurring revenue. Find contacts whose total subscription value exceeds a threshold, or those who subscribed recently.
- **Lead** - Measure lead generation. Identify high-value leads or contacts who converted from specific campaigns.
- **Signup** - Track account creation and onboarding. Segment new signups from the past week or users who completed registration.
- **Booking** - Track appointments and reservations. Find contacts with upcoming bookings or those who booked multiple times.
- **Trial** - Monitor trial usage and conversion. Segment trial users by their engagement level or trial start date.
- **Other** - Track any custom conversion goal specific to your business.

**What you can measure:**
- Total value (sum of all events)
- Number of events (count)
- Average value per event
- Minimum or maximum event value

**Filter by time:**
- All time
- In the last X days
- Within a specific date range
- Before or after a specific date

<img width="1235" height="654" alt="Screenshot 2025-11-29 at 18 52 04" src="https://github.com/user-attachments/assets/39a922d4-5e55-4a51-a54f-67271469642d" />


### Database Schema Changes

- New `custom_events` table for tracking user behavior and goals
- Added computed fields in segmentation engine for custom events goal aggregations
- Contact timeline event kinds renamed to semantic dotted format (existing data migrated automatically)

### Breaking Changes

#### Removed Contact Fields

The following deprecated contact fields have been removed:
- `lifetime_value`
- `orders_count`
- `last_order_at`

**Action Required:** Segments using these deprecated fields will be deleted during migration. Use the new Custom Events Goals system instead.

#### Timeline Event Kinds Renamed

Event kinds now use semantic dotted format:

| Old Format | New Format |
|------------|------------|
| `insert_contact` | `contact.created` |
| `update_contact` | `contact.updated` |
| `insert_contact_list` | `list.subscribed` / `list.pending` |
| `join_segment` | `segment.joined` |
| `leave_segment` | `segment.left` |

Status changes map to: `list.confirmed`, `list.resubscribed`, `list.unsubscribed`, `list.bounced`, `list.complained`

#### Segment Tree Field Renamed

The `TreeNodeLeaf.table` field has been renamed to `source`. Existing segments are migrated automatically.

### Migration Notes

- Migration v18.0 runs automatically on startup
- Existing timeline data is migrated to new event kind format
- Segments with deprecated contact fields are removed
- Segment tree structures are updated to use `source` instead of `table`

---

**Upgrade Path:** Update your Docker image to `notifuse:v18.0` and restart. The migration runs automatically.