Skip to content

Notifications overview

Notifications allow the system to inform external systems when important events occur.

They are used to synchronize data, trigger automation, and allow other systems to react to changes without continuously polling the API.

Notifications are delivered using signed webhooks. When an event occurs, the system sends a message to a configured external endpoint.

What notifications are

A notification is an event message sent to another system.

Instead of repeatedly asking the system if something changed, external systems can receive notifications whenever relevant events occur.

Notifications are intentionally lightweight. They normally contain:

  • the identifier of the webhook configuration
  • the identifiers of affected rows

The receiving system can then retrieve full data using the API if additional information is required.

This design keeps notifications small and avoids sending large amounts of data unnecessarily.

Event families

Notifications can be triggered by two types of events.

Classification events

Classification events occur when the result of a boolean classification changes state for a row.

Examples include:

  • a customer becoming active
  • a contract becoming valid
  • a booking becoming confirmed

These events detect state transitions, meaning the notification is triggered when the classification changes from one state to another.

Mutation events

Mutation events occur when data changes in the system.

Examples include:

  • a row being created
  • a row being updated
  • a row being deleted
  • a relation being added or removed

Mutation events are typically used for external synchronization, allowing other systems to stay aligned with changes in the data model.

Delivery model

Notifications are delivered using webhooks.

When an event occurs, the system:

  1. creates a notification payload
  2. signs the payload using the configured authentication method
  3. sends an HTTP POST request to the configured endpoint

A delivery attempt is considered successful only if the receiving system returns HTTP 200.

If delivery fails, the system automatically retries the request.

Notifications follow an at-least-once delivery model, which means the same notification may be delivered more than once. Receiving systems should therefore handle duplicate messages safely.

How-to

Related concepts