Events

An event is each occurrence sent to the platform via the POST /events endpoint.

While the event type defines the contract, the event represents the actual data that occurred in the operation (for example: a payment attempt, an authentication, or a registration update).

Every event belongs to an event type

To send an event, you must specify in the type attribute which event type it represents.

This value must be the ID of a previously configured and active event type in the account.

If the event type does not exist or is inactive, the API rejects the submission.

Minimum submission structure

When submitting to POST /events, the main fields are:

  • type: event type ID;
  • id: unique identifier of the event;
  • attributes: event data according to the fields configured in the type;
  • timestamp (optional): date and time of the occurrence. If not provided, the platform uses the reception time;
  • rule.name (optional): name of the rule to run over this event. Without this attribute, the event type’s default rule applies, if there is one.

Field names starting with _ or % are reserved by the platform, and the submission is rejected if any of them appears in attributes.

Inheritance between events under the same id

Several posts can share the same id, representing the same occurrence at different stages: the creation of an order and, minutes later, its outcome. A later post does not need to repeat everything already provided.

Each field of the event type defines whether it takes part in this inheritance, through the Inheritance setting. When it is on, a post that omits the field receives the value left by the previous post; when it is off, the field holds only for the post that carried it.

What is inherited is the event as it was recorded, including the fields filled by a rule during processing, and not only what the client sent. Inherited values apply everywhere: in the recorded event, in the rule’s conditions and in the analyses.

Sending the field with the value null clears the inherited value, and later posts do not recover it. Omitting the field keeps the inheritance.

Inheritance has a deadline, configured in the event type. Once that deadline passes with no new posts under the same id, the accumulated values are discarded and a later post holds exactly for what it carries.

How validation works

Event validation follows the event type configuration:

  • required fields must be sent;
  • data types must be in the expected format;
  • unknown fields can be ignored or rejected, depending on the event type configuration.

This ensures consistency in ingestion and prevents out-of-contract events from affecting metrics and monitors.

What the response returns

The response carries the event’s id and every field of the event type, including those filled in by a rule during processing. An event sent with three fields may come back with five, if a rule enriched the other two.

Fields reserved by the platform are written to the event but do not appear in the response.

Practical example

  1. You register an event type with ID transaction.
  2. Define the expected fields, such as amount and status.
  3. Send an event to POST /events with type: transaction.
  4. The platform validates the payload, runs the event type’s rule (if there is one), and processes the event for use in analyses, metrics, and monitors.