record.updated

This event fires once per field, not once per save. A form that writes six fields to one record produces six deliveries, each naming a different propertyId. Debounce on recordId if you only care that the record moved.

Payload

{
  "id": "whd_7Kc2pR4nM",
  "event": "record.updated",
  "createdAt": "2026-09-11T14:22:07.118Z",
  "data": {
    "recordId": "rec_3Ab9xK2mQ7",
    "objectId": "obj_2Zc7pL",
    "propertyId": "prop_5Nd3kR",
    "previous": ["opt_qualified"],
    "current": ["opt_negotiation"],
    "record": {
      "id": "rec_3Ab9xK2mQ7",
      "name": "Ravenna Foods",
      "stage": ["opt_negotiation"],
      "annual_value": 48000
    }
  }
}

string

required

The record that changed.

string

The object it belongs to.

string

The prop_… id of the one property this delivery is about. Resolve it against the object’s schema to get its key and name.

any

The value before the change, in stored shape. null means the field was genuinely empty. The key being absent means no prior value could be read, which is a different thing.

any

The value after the change. null means the field was cleared.

object

The whole record after the change, keyed by property key, plus an id key holding the record id.

Why `record` is there as well

Because it saves you a round trip in the common case. The changed field is named by propertyId, and record gives you the state the record is now in, so a handler that needs three fields to make a decision has them without calling back.

record here carries an id key, which record.created does not. That asymmetry comes from the emitters and is faithful to what is actually sent.

Naming the property

propertyId is an id, not something to show a person. Read the object’s schema once and cache the map:

const object = await custral.objects.retrieve("deals");
const byId = new Map((object.properties ?? []).map((p) => [p.id, p]));

custral.on("record.updated", (event) => {
  const property = byId.get(event.data.propertyId as string);
  console.log(`${property?.name ?? "A field"} changed on ${event.data.recordId}`);
});

Worth knowing

Order is not guaranteed. Two changes to the same record can arrive out of order, so record is the more trustworthy view of current state than replaying current values in arrival order. If it matters, read the record back.
Bulk edits are suppressed, along with imports and AI property fills.
Computed properties. A formula or rollup recalculating is not itself a field write and does not reliably produce this event. Treat computed values in record as a snapshot rather than a trigger.

Example

custral.on("record.updated", async (event) => {
  const {recordId, propertyId, previous, current, record} = event.data;

  if (propertyId !== process.env.STAGE_PROPERTY_ID) return;

  const from = Array.isArray(previous) ? previous[0] : previous;
  const to = Array.isArray(current) ? current[0] : current;
  if (to !== process.env.CLOSED_WON_OPTION_ID) return;

  await billing.startSubscription({
    account: String(record?.name ?? recordId),
    value: Number(record?.annual_value ?? 0),
    movedFrom: from,
  });
});

Getting started

Building a receiver

Event reference

Operations

Payload

Why `record` is there as well

Naming the property

Worth knowing

Example

​Payload

​Why record is there as well

​Naming the property

​Worth knowing

​Example

Payload

Why `record` is there as well

Naming the property

Worth knowing

Example