Skip to main content

Custom Events

Custom events let you tell Arsel about things that happen in your product or systems — an order completed, a trial started, a feature used — and act on them: trigger automations, segment contacts, and personalize messaging.

A custom event has two parts:

  1. A definition — a named schema you create once (e.g. order.completed with the fields it carries).
  2. Sends — individual occurrences you report against that definition for a specific contact.

How it works​

Define event  ──►  Send events  ──►  Validate against schema  ──►  Trigger automations
(once)             (per occurrence)   (accepted / rejected)         (in real time)
  1. You define the event and its field schema — once, up front.
  2. Your application sends an event each time it happens, identifying the contact and attaching a data payload.
  3. Arsel validates the payload against the schema. Accepted events are recorded; payloads that don't match are rejected.
  4. Automations subscribed to the event fire for the matching contact.

Defining an event​

An event definition has:

  • Name — a unique identifier for your organization, such as order.completed or trial.started. The name is immutable once created.
  • Description — optional, human-readable.
  • Schema — a list of fields each event payload may (or must) include. Each field has a name, a type (string, number, boolean, or date), and whether it is required.

You can manage event definitions from the Arsel dashboard, or via the API — see Create Event.

Naming convention

A noun.verb convention (order.completed, subscription.cancelled) keeps events readable and groups related events together.

Sending events​

Each send identifies the contact in one of these ways:

  • email — the contact's email address.
  • phone_number — the contact's phone number in E.164 format (e.g. +966501234567).
  • contact_id — an existing contact's ID.

Provide at least one of email or phone_number (you may send both), or contact_id on its own — contact_id cannot be combined with email/phone_number. If no contact matches the email or phone number, one is auto-created when the automation runs. When both email and phone_number are supplied, email is authoritative.

The send also carries a data payload, which is validated against the event's schema. See Send Event for the API.

Validation​

When a payload is sent:

  • Required fields must be present.
  • Field types must match the schema (number fields must be numbers, etc.).

If validation fails, the event is rejected and recorded as such — it does not trigger automations. If it passes, it is accepted and processed asynchronously.

Triggering automations​

Once an event is defined, you can build an automation that starts whenever that event is received. The event's payload fields are available downstream in the automation, so you can branch on them or use them in messaging.

Conversions & revenue​

Any custom event can be marked as a conversion — an outcome you care about, such as a completed order or a started subscription. Conversions feed goal tracking and revenue reporting, and (for monetary conversions) carry a money amount.

The revenue value and currency are read from fields on the event's own schema:

  • Value field — a number field holding the amount (e.g. total). Omit it (send null) for a count-only conversion that tracks occurrences without revenue.
  • Currencies — the ISO-4217 codes you accept (e.g. SAR, USD). With a single currency it is fixed for every event; with more than one, each event's currency is read from a currency field on the schema.

You can configure this from the Arsel dashboard, or via the API when you create or update an event by passing a conversion object:

{
  "conversion": {
    "enabled": true,
    "value_field": "total",
    "currencies": ["SAR", "USD"],
    "currency_field": "currency"
  }
}
Explicit value field via the API

The API never guesses the revenue field — when enabling a conversion you must name the value_field (or send null for count-only). Reporting is per-currency; amounts in different currencies are never summed together.

Conversion tracking is go-forward only: only events received after a conversion is enabled are counted.

Next steps​