Reporting and Canceling Events

Before diving in, it's important to understand the difference between a trigger and an event and what all this means for your users.

A trigger is the configuration you create for your app in your app's dashboard. On the other hand, an event is what takes place in your service, which you then report to Wix.

The distinction between triggers and events is hidden from your users. From their perspective,they interact with triggers only. Users who install your app are able to use your triggers when they create new automations for their site. When your app reports an event, all site automations that use the specified trigger are activated.

Event types

Wix Automations supports 2 types of events for triggers: real-time events and scheduled events.

Each trigger can support either real-time events or scheduled events, but not both. However, you can call reportEvent() multiple times in response to a single business event in your system.

This table lays out the differences between real-time events and scheduled events:

Real-time event	Scheduled event
Takes place the moment it's reported.	Takes place at a date and time specified in the payload.
Supported by default in new triggers.	Supported only when your trigger meets both of these criteria: A date-time property is specified in the trigger's payload schema. You select the Allow scheduled events with predefined date & time option in your trigger configuration.
Supports automation actions: Immediately when the event is reported. After the event is reported.	Supports automation actions: At the event time in the payload. Before the event time in the payload. After the event time in the payload.

Canceling events

Your users may configure actions to be carried out some time after you report an event. If you create a trigger for something that could be canceled or deleted, we strongly recommend canceling events when they're no longer relevant. If your app doesn't cancel events, your users' automations may carry out undesired actions, like sending overdue notices for invoices after they've been paid.

Events are not cancelable by default. To make an event cancelable, you must first pass an externalEntityId and the applicable triggerKeyto reportEvent(). When you call cancelEvent() with the same externalEntityId and triggerKey, the event is canceled, as are all other events that share the same externalEntityId and triggerKey.

Choose the right externalEntityId

It's important to know that the Cancel Event endpoint cancels all events with the specified combination of triggerKey and externalEntityId. You must think through your implementation carefully to make sure you don't pass an externalEntityId that could cancel events you don't mean to cancel.

Consider what kind of relationship between entities you're trying to support. These general guidelines might help you decide what ID to use for externalEntityId:

• If you're supporting a one-to-many relationship, use the ID from the many side of the relationship.

  For example, in a contact-to-invoices relationship: An invoice relates to a single contact, but a contact can relate to multiple invoices. The invoice ID is the appropriate externalEntityId.

• If you're supporting a many-to-many relationship, create a unique event ID for each reported event.

  For example, in a students-to-classes relationship: Each student relates to multiple classes, and each class relates to multiple students. A new event ID is the appropriate externalEntityId.

Scenario 1: One-to-many relationship

The scenario: Customers can schedule appointments with site collaborators.

Suggested value for externalEntityId: Appointment ID

Suggested triggers and how your users might use them:

Trigger key and description	How your users might use the trigger
appointment_scheduled Real-time event. Triggered when someone schedules an appointment.	Immediately send a confirmation email to the customer. Immediately send a notification to site collaborators.
appointment_starting Scheduled event. Triggered in relation to the appointment's start time.	Send a reminder email x days before the appointment. Notify the applicable site collaborator x minutes before the appointment.
appointment_canceled Real-time event. Triggered when someone cancels an appointment.	Immediately send a cancellation email to the customer. Immediately notify site collaborators of the cancellation.

Example logic for your app:

Business event	Your app's API calls
Customer schedules an appointment	Report appointment_scheduled event. Report appointment_starting event.
Customer cancels an appointment	Report appointment_canceled event. Cancel appointment_scheduled event. Cancel appointment_starting event.

Scenario 2: Many-to-many relationship

The scenario: Participants can enroll in multiple courses. Each course can contain multiple participants.

Suggested value for externalEntityId: A generated enrollment ID, unique to each student-class combination.

Suggested triggers and how your users might use them:

Trigger key and description	How your users might use the trigger
participant_enrolled_in_class Real-time event. Triggered when someone signs up for a class.	Immediately send a confirmation email to the participant. Immediately send a notification to the site owner.
class_starting Scheduled event. Triggered in relation to the class's start time.	Send a reminder email x days before the class. Notify the site owner x minutes before the class.
participant_left_class Real-time event. Triggered when someone is unenrolled from a class.	Immediately send a confirmation email to the participant. Immediately notify the site owner that someone left their class.
class_canceled Real-time event. Triggered when a class is canceled.	Immediately send a confirmation email to each participant. Immediately notify the site owner that a class is canceled.

Example logic for your app:

Business event	Your app's API calls
Participant enrolls in a class	Report participant_enrolled_in_class event. Report class_starting event.
Participant leaves a class	Report participant_left_class event. Cancel participant_enrolled_in_class event. Cancel class_starting event.
Class is canceled	Report class_canceled event. Cancel participant_enrolled_in_class event. Cancel class_starting event.