Events

Model events allow you to track and respond to changes in your data. When a record is created, updated, or deleted, Swell checks whether certain conditions are met and generates an event record with metadata about the event. These records can be analyzed using the backend API, and are typically used to constitute activity feeds and to trigger webhooks.

→ See the event reference for more details.

Swell provides three standard event types for any model: created, updated, and deleted. Each event type includes specific data:

These standard events can be enabled or disabled on any model. The event record contains the full object that was changed under the data property, along with additional metadata.

Some models have specific event types related to their unique functionality, such as:

For example, the payment.succeeded event fires when a payment record is created or updated with the success property. If any webhooks are configured for the event, they will be processed asynchronously.

Apps can define new event types for standard or custom models, extending the range of events you can track and respond to in your application.

You can define and specify when an event should be triggered based on specific criteria using conditions. They are formatted similarly to API query filters used for record retrieval. Event conditions support a range of operators, including Swell-specific operators like $record, $data, and $method, as well as common MongoDB query operators such $eq, $ne, $gt and more. These operators provide a flexible way to define conditions based on various aspects of your data and its changes. A conditions criteria can also leverage a $formula property to evaluate data using Swell’s formula syntax.

You can configure events on a model to trigger custom logic or integrations when specific actions occur, such as creating, updating, or deleting a record. These events can be subscribed to by webhooks and functions.

To define events on a model, you can add an events property in the model configuration file. Here's a simple example of defining events on the "things" model:

{
  "collection": "things",
  "label": "Things",
  "fields": {
    "name": {
      "type": "string",
      "required": true
    },
    "description": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive"]
    }
  },
  "events": {
    "enabled": true,
    "types": [
      { "id": "created" },
      { "id": "updated" },
      { "id": "deleted" },
      {
        "id": "activated",
        "conditions": {
          "status": "active",
          "$record": {
            "status": { "$ne": "active" }
          }
        }
      }
    ]
  }
}

In this example, we've defined three standard events: created, updated, and deleted. These events are triggered by the corresponding actions on the "things" model. Note that it's also possible to add conditions to these standard events.

Also in this example, we've added a new field called status to the "things" model with two possible values: active and inactive, and defined a custom event called activated, which is triggered when a Thing changes its status from inactive to active.