> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Benutzerdefinierte Ereignisse & Ziele

> Erfassen Sie Nutzerverhalten und Conversion-Ziele, um RFM-Segmente zu bilden und den Kontaktverlauf anzureichern.

## Überblick

Benutzerdefinierte Ereignisse erfassen Aktionen von Nutzern aus externen Systemen (E-Commerce, CRM, Analyse). Sie erscheinen im Kontaktverlauf, und mit ihren Zielen bilden Sie RFM-Segmente (Recency, Frequency, Monetary).

## Kontaktverlauf

Jedes benutzerdefinierte Ereignis legt einen Eintrag im Kontaktverlauf an, sodass Sie die gesamte Geschichte der Interaktionen eines Kontakts sehen:

![Kontaktverlauf mit benutzerdefinierten Ereignissen](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

Jedes Ereignis zeigt seinen `event_name` als Typ des Verlaufseintrags (z. B. „order.completed“, „subscription.started“). Das Feld `properties` speichert zusätzlichen Kontext, der in den Details des Verlaufseintrags sichtbar ist.

## Zieltypen

Segmente bauen auf Zielen auf. Jedes Ereignis kann ein Ziel erfassen:

| Typ            | Anwendungsfall                           | goal_value   |
| -------------- | ---------------------------------------- | ------------ |
| `purchase`     | E-Commerce-Bestellungen, Einmalzahlungen | Erforderlich |
| `subscription` | SaaS-Abonnements, Mitgliedschaften       | Erforderlich |
| `lead`         | Kontaktformulare, Demo-Anfragen          | Optional     |
| `signup`       | Kontoregistrierungen                     | Optional     |
| `booking`      | Termine, Beratungen                      | Optional     |
| `trial`        | Aktivierungen kostenloser Testphasen     | Optional     |
| `other`        | Eigene Conversion-Ereignisse             | Optional     |

## RFM-Segmente bilden

Die RFM-Analyse (Recency, Frequency, Monetary) findet Ihre besten Kunden. Verwenden Sie im Segment-Builder Bedingungen vom Typ **Ziel**:

![Segment-Builder mit einem Ziel aus benutzerdefinierten Ereignissen](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### Monetär: Gesamtausgaben

Wählen Sie den Zieltyp **Kauf** und die Aggregation **Summe** und legen Sie dann einen Mindestwert fest, um Kunden mit hohen Ausgaben zu finden.

### Häufigkeit: Anzahl der Käufe

Wählen Sie den Zieltyp **Kauf** und die Aggregation **Anzahl** und legen Sie dann eine Mindestzahl fest, um Wiederkäufer zu finden.

### Aktualität: Aktuelle Aktivität

Verwenden Sie den Zeitraumfilter „in den letzten X Tagen“, um Kunden mit aktuellen Käufen zu finden.

### Beispiele für RFM-Segmente

- **VIP-Kunden**: Ausgaben ab 1000 $ UND ab 5 Bestellungen UND Kauf in den letzten 60 Tagen
- **Gefährdete Kunden mit hohem Wert**: Ausgaben ab 500 $ UND kein Kauf in 90 Tagen
- **Neue Kunden mit hohem Potenzial**: Erster Kauf über 200 $ in den letzten 30 Tagen

### Aggregationsoptionen

| Option       | Beschreibung                                                 |
| ------------ | ------------------------------------------------------------ |
| Summe        | Summe aller Zielwerte (Gesamtausgaben)                       |
| Anzahl       | Anzahl der Ereignisse (Zahl der Bestellungen)                |
| Durchschnitt | Durchschnittlicher Zielwert (durchschnittlicher Bestellwert) |
| Minimum      | Kleinster Zielwert                                           |
| Maximum      | Größter Zielwert                                             |

### Zeitraumoptionen

| Option                 | Beschreibung                |
| ---------------------- | --------------------------- |
| Jederzeit              | Alle historischen Daten     |
| In den letzten X Tagen | Gleitendes Zeitfenster      |
| Im Datumsbereich       | Bestimmter Zeitraum         |
| Vor Datum              | Historischer Stichtag       |
| Nach Datum             | Seit einem bestimmten Datum |

## Ereignisse erfassen

### Einzelnes Ereignis

```bash
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "email": "customer@example.com",
    "event_name": "order.completed",
    "external_id": "order_12345",
    "properties": {
      "items": ["Product A", "Product B"],
      "currency": "USD"
    },
    "goal_type": "purchase",
    "goal_value": 149.99
  }'
```

### Stapelimport

Importieren Sie bis zu 50 Ereignisse auf einmal:

```bash
curl -X POST "https://your-instance.com/api/customEvents.import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "events": [
      {
        "email": "user1@example.com",
        "event_name": "order.completed",
        "external_id": "order_001",
        "goal_type": "purchase",
        "goal_value": 99.99
      },
      {
        "email": "user2@example.com",
        "event_name": "order.completed",
        "external_id": "order_002",
        "goal_type": "purchase",
        "goal_value": 249.99
      }
    ]
  }'
```

## Format von Ereignisnamen

Ereignisnamen müssen kleingeschrieben sein und dürfen Buchstaben, Ziffern, Punkte, Unterstriche, Bindestriche oder Schrägstriche enthalten:

- `order.completed`
- `subscription/started`
- `form_submit`
- `user-signup`

> [!NOTE]
>
> Ziele, die die [Web-Analyse](https://www.notifuse.com/de/docs/web-analytics/goals.md) erfasst, gelangen nach einer engeren Regel in den Kontaktverlauf: nur ASCII-Buchstaben, Ziffern, Punkte und Schrägstriche, alles andere (auch Bindestriche und Zeichen mit Akzent) wird durch einen Unterstrich ersetzt. Ein Web-Ziel namens `user-signup` kommt als `user_signup` an. Wenn Sie dasselbe Ereignis über beide Wege senden, wählen Sie einen Namen, der beide Regeln übersteht.

## Rückerstattungen behandeln

Verwenden Sie für Rückerstattungen einen negativen `goal_value`, damit die LTV-Berechnungen stimmen:

```json
{
  "email": "customer@example.com",
  "event_name": "order.refunded",
  "external_id": "refund_12345",
  "goal_type": "purchase",
  "goal_value": -50.00
}
```

## Berechtigungen

Benutzerdefinierte Ereignisse haben keine eigene Berechtigung, sie unterliegen **Kontakte**. Ein Ereignis zu erfassen oder zu importieren braucht bei Kontakte **Schreiben**, es zu lesen **Gelesen**. Wer Lesezugriff auf Kontakte vergibt, öffnet damit auch die zu Ihren Kontakten erfassten Ereignisse und den Kontaktverlauf, den sie speisen. Siehe [Admins & API-Schlüssel](https://www.notifuse.com/de/docs/features/admins-api-keys.md).

## Hinweise

- `customEvents.upsert` legt den Kontakt an, wenn es keinen Kontakt mit dieser E-Mail-Adresse gibt. `customEvents.import` legt keinen Kontakt an
- Ereignisse werden nur aktualisiert, wenn `occurred_at` neuer ist als der vorhandene Wert
- Soft Delete durch Setzen von `deleted_at` (auf `null` setzen, um wiederherzustellen)
- Nur ein neues Ereignis (eine neue `external_id`) startet die Automatisierungen, die durch seinen Namen ausgelöst werden; seit 44.0 tut das eine Aktualisierung, ein Soft Delete oder eine Wiederherstellung nicht mehr
- Die vollständige Dokumentation der Endpunkte finden Sie in der [API-Referenz](https://www.notifuse.com/docs/api-reference/import-custom-events.md)
