Payload format

Every delivery is the same envelope. Only data changes shape between events.

The envelope

{
  "id": "whd_3JAx8Qm2rL9pKd",
  "event": "record.created",
  "createdAt": "2026-09-11T14:18:54.201Z",
  "data": {
    "recordId": "rec_3Ab9xK2mQ7",
    "objectId": "obj_2Zc7pL",
    "record": {"name": "Ravenna Foods", "stage": ["opt_negotiation"]}
  }
}

string

required

The delivery id, prefixed whd_. Unique per delivery, stable across retries of that delivery. This is the key to deduplicate on.

string

required

The event name, for example record.updated. Also sent as the X-Custral-Event header so you can route before parsing the body.

string

required

ISO-8601 timestamp, generated at the moment of this attempt. It is not the time the underlying event happened, and it moves between retries.

object

required

The event payload. Each event’s fields are documented in the event catalog.

Headers

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Custral-Webhooks/1.0`
`X-Custral-Event`	The event name, matching `event` in the body
`X-Custral-Signature`	`t=<unix seconds>,v1=<hex hmac>`, see Verifying signatures

Absent is not the same as cleared

Payloads are built field by field, and a field with no value is omitted rather than sent as null. So a key that is missing means Custral had nothing to put there; a key present and null means the value was genuinely emptied. On record.updated that distinction is the whole point of the event: "previous": null says the field used to be empty, while no previous key at all says the emitter could not read a prior value.

Field values are STORED values, not display values

This is the one that catches people. A record’s fields arrive exactly as Custral stores them, which for several property types is a list of ids rather than anything you would show a person.

Property type	Arrives as
Text, long text, email, phone, website	The string
Number, currency	The number
Date	The stored date value
Checkbox	The boolean
Select, status	`["opt_3Kd8sM"]`, an option id
Relation	`["rec_9Lm2pQ"]`, a record id
User	`["user_5Nc1rT"]`

"record": {
  "name": "Ravenna Foods",
  "annual_value": 48000,
  "stage": ["opt_3Kd8sM"],
  "owner": ["user_5Nc1rT"]
}

To turn opt_3Kd8sM into "Negotiation", read the object’s schema once and cache it:

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

labels.get("opt_3Kd8sM"); // "Negotiation"

Resolving these to labels inside the payload needs a bulk lookup on every event, so it is a deliberate follow-up rather than something quietly added. Until it lands, the ids are what arrive, and GET /v1/objects/{id} is how you name them.

Keys are property keys

The record object on both record events is keyed by each property’s key (annual_value), not its display name and not its prop_… id. Keys are stable across renames, which is what makes them safe to write code against. See How the schema works. A field whose property key cannot be resolved is dropped from record rather than included under an empty key.

Typing the payload

CustralEvent is generic over data, so you can narrow per event:

import type {CustralEvent} from "@custral/sdk";

interface RecordCreated {
  recordId: string;
  objectId?: string;
  record?: Record<string, unknown>;
}

custral.on("record.created", (event: CustralEvent<RecordCreated>) => {
  event.data.recordId;
});

Getting started

Building a receiver

Event reference

Operations

The envelope

Headers

Absent is not the same as cleared

Field values are STORED values, not display values

Keys are property keys

Typing the payload

​The envelope

​Headers

​Absent is not the same as cleared

​Field values are STORED values, not display values

​Keys are property keys

​Typing the payload

The envelope

Headers

Absent is not the same as cleared

Field values are STORED values, not display values

Keys are property keys

Typing the payload