The Payload Schema

When you configure your app's triggers, you must provide a payload schema. The payload schema defines the required and validated fields in your event payloads, and it's used to display available options to your users when they configure their automations.

A payload schema allows you to define scheduled events and can give your users enriched payloads by linking your trigger to a site contact. Wix also uses the payload schema to determine the available actions for a trigger.

The payload schema must be a JSON Schema object. See the tables below for the expected structure.

Schema properties

These properties are at the schema's root level.

Property	Data type	Description
$schema	string	When you save the trigger configuration, Wix overrides this property to set it to "http://json-schema.org/draft-07/schema".
type	string	Required. Must be "object".
properties	object	Required. Object containing payload property metadata as key-object pairs. See the properties object below for details.
required	array	List of property keys that are required to be present in the reported event payload.
additionalProperties	boolean	When you save the trigger configuration, Wix overrides this property to set the value to true, which allows additional, unspecified properties to be sent in the payload.

The properties object

properties is an object that contains key-object pairs.

The key name can include only alphanumeric characters or underscores (A-Z, a-z, 0-9, _). It cannot start with an underscore.

The paired object contains display and validation metadata. This table gives the expected data structure:

Property	Data type	Description
type	string	Supported values: string, number, integer, boolean, array, object. Required. Expected data type of the payload property. Note: Only the 1st-level properties object supports "object" and "array" types.
title	string	Required. Display name for the property. Shown to users when they create or edit an automation.
examples	array	Example values, displayed as placeholders when users test certain automation actions. Must be the same data type defined in type. Required in the 1st-level properties object. Omitted in the 2nd-level properties object.
format	string	Validated string format. Used only when type is "string". See built-in formats (from the JSON Schema 2020-12 docs) for supported formats. If set to "uuid", the property can be connected to a site's contacts. This allows Wix to enrich the payload with contact data and allows the site owner to use actions that work with their contacts. If set to "date-time", the property can be used to add support for scheduled events.
identityType	string	Supported value: contact If the property is specified with Connect a property to a contactId, identityType is automatically set to "contact". In all other cases, identityType is omitted. Limited to 1 payload property.
futureDate	boolean	If the property is specified with Allow scheduled events with predefined date & time, futureDate is automatically set to true. In all other cases, futureDate is omitted. Limited to 1 payload property.
items	object	Object that contains a list of array items. Required if type is "array". Omitted for other data types. See the items object below for details.
properties	object	Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level properties object, but can contain only strings, numbers, integers, or booleans. Required if type is "object". Omitted for other data types.
required	array	List of property keys that are required to be present in the reported event payload. Used only when type is "object" or "array".

The items object

items is an object that contains an array schema. Wix Automations supports arrays of objects only.

Property	Data type	Description
type	string	Required. Must be set to "object".
properties	object	Required. Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level properties object, but can contain only strings, numbers, integers, or booleans. See the properties object above for details.
required	array	List of property keys that are required to be present in the reported event payload.

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 the Wix Developers Center. On the other hand, an event is what takes place in your service, which you then report to Wix. (For more complete definitions, see Terminology in the introduction to this API.)

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 Report Event 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.

About 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 Report Event. When you call Cancel Event 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.