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 two ways:

  • email — if no contact with that email exists yet, one is auto-created when the automation runs.
  • contact_id — an existing contact's ID.

Provide exactly one. 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.

Next steps​