Skip to content

Mutation notification events

Mutation notification events are produced when data changes in the system.

They allow external systems to react to inserts, updates, deletions, and relationship changes without continuously polling the API.

These events are commonly used to keep external systems synchronized with the data model.

Examples include:

  • a new customer being created
  • a product being updated
  • a contract being deleted
  • a relationship between two records being added or removed

Mutation events track data changes, not classification state changes.

Event list

Each mutation notification event monitors changes starting from a source table.

From this starting point, the event can observe:

  • row creation
  • row updates
  • row deletion
  • relation creation
  • relation removal
  • changes to specific fields
  • changes in related tables

Because mutation events follow the data model, changes can propagate through relations and affect multiple related entities.

Trigger conditions

Mutation events are triggered when a write operation completes successfully.

Possible triggers include:

  • inserting a new row
  • modifying one or more columns
  • deleting a row
  • adding a relation between rows
  • removing a relation between rows

Events are evaluated after the write operation finishes, ensuring that only committed changes generate notifications.

This ensures that receiving systems are notified only about changes that are successfully stored.

Payload specifics

Mutation events produce the standard notification payload.

The payload normally includes:

  • the webhook identifier
  • the identifiers of rows affected by the mutation

The payload does not contain full row data. External systems are expected to retrieve detailed information using the API if needed.

This keeps notification messages small and efficient.

Order and duplication semantics

Mutation notifications follow the system's general delivery model.

This means:

  • delivery follows an at-least-once model
  • the same notification may be delivered more than once
  • no global ordering guarantee exists across events

Receiving systems should therefore treat events as idempotent and be able to safely ignore duplicates.

How-to

Related concepts