Skip to main content

Webhooks V2

Endpoints configured at the organization level, each receiving a chosen set of event types from the workspaces it covers. An organization can configure more than one endpoint, and each one covers its own workspaces and event types. No rule to create in each workspace: an endpoint's coverage is set once at the organization level.

Organization webhooks are Gravity Rail's only outbound webhook system. They replace Webhooks v1, the per-workspace Send Webhook Action, which has been retired. If you are moving an integration built on v1, Webhooks v1 → v2 covers what maps across and what does not.

Configure endpoints at Organization → Webhooks.

What you get​

ScopeAll of the organization's workspaces, selected workspaces (named, labelled, or both), or none
VocabularyA closed set of activity event types — see the catalog
PayloadOne shape for every event type. Identifiers only
DeliveryA durable queue: at-least-once, retried for up to a day, held for 7 days
SigningHMAC-SHA256 over the raw body — see Request signing
TestingA Send test event button on every endpoint, with an editable payload

Setting one up​

  1. Go to Organization → Webhooks and create an endpoint: a name, an HTTPS URL, and the event types it subscribes to. Production rejects http:// URLs and private, loopback, link-local and internal hosts, so the endpoint must be publicly resolvable.
  2. Choose which workspaces it covers: All workspaces (every workspace in the organization, including ones created later — the editor's default), Selected workspaces (specific workspaces, workspace labels, or both), or No workspaces. Over the API this is the required workspaceScope object — see Notes on the shapes.
  3. Save the signing secret. It is generated for you unless you supply your own, and it is returned exactly once, in the create response. Every later read shows a masked placeholder (__SECRET_SET__); sending that placeholder back on update preserves the stored secret, and sending any other value rotates it.
  4. Press Send test event to confirm a correctly signed request reaches your receiver. A 2xx does not show your handler acted on the payload or verified the signature. See Testing below.

A selected endpoint covers its linked workspaces plus every workspace that carries all of the labels in its label selector. Labels are your organization's own taxonomy — production, test, a sponsor or customer name — set on each workspace by an organization admin (Organization → Workspaces, or gr workspaces create --labels … / gr org workspaces labels set). Labels are read as each event is matched to endpoints, so a workspace labelled production today starts feeding every endpoint that selects on production with no change to the endpoint, and removing the label stops it. There is no exclude mode: "every workspace except the test ones" is a selector on whatever label your live workspaces carry. Because a selector needs every label it names, adding a label to it can only narrow it, and a label that a selector uses cannot be deleted until no endpoint selects on it.

Event types are drawn from the closed vocabulary below, narrowed to the types deliverable at workspace visibility — an org-only event (billing, domain verification) is rejected when you configure it, rather than accepted and then silently never sent.

Who can do what​

Read endpoints, the vocabulary, the delivery logorg:webhooks — org admins hold it automatically
Create, update, delete, send a testOrg admin, subject to the organization's interactive MFA policy
See which org endpoints your workspace feedswebhooks:read inside that workspace

Every create, update and delete of an endpoint's configuration is written to the admin-config audit log. Status changes (pause, resume, the system's own historical automatic disables) live in the endpoint's status history. A test send is recorded separately again — it changes no configuration, but it is an outbound request our infrastructure made on an operator's say-so.

Payload​

One shape for every event type: the raw activity event envelope, plus which endpoint delivered it. There are no per-family variants to learn.

It carries identifiers only — no member names, no message content, no DataRecord field values. Resolve what you need through the API using the ids in subject, refs and detail.

{
"id": "6c87845e-73e3-538a-9e9b-a197023cf884",
"occurred_at": "2026-01-15T14:22:00Z",
"event_type": "member.created",
"event_version": 1,
"visibility": "workspace",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": "3c8c25ca-c126-52f7-8a1b-3a40ba93c609",
"account_uuid": null,
"actor": { "kind": "system", "uuid": null },
"subject": {
"kind": "member",
"uuid": "5ec1da83-d1c9-5aa7-849c-a6fcb0d18631",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": null,
"account_uuid": null
},
"refs": [],
"detail": {
"schema_version": 1,
"backfill": false,
"type": "member.created",
"origin": "api",
"connection": null,
"account": null,
"capabilities": ["members:read"]
},
"dedupe_discriminator": null,
"dedupe_key": "member.created:member:5ec1da83-d1c9-5aa7-849c-a6fcb0d18631",
"endpoint": {
"uuid": "9c1f7e5a-1b2c-4d3e-8f90-a1b2c3d4e5f6",
"name": "Acme CRM sync"
}
}
FieldWhat it is
idThis occurrence's own uuid
occurred_atWhen it happened, UTC, timezone-aware
event_typeOne of the catalog values
event_versionEnvelope version. Bumped only if the envelope's own shape changes
visibilityAlways workspace on a delivered event
workspace_uuidThe workspace the event rolled up under
org_uuidAlways the delivering endpoint's organization, whatever the underlying event recorded
account_uuidThe account, when the occurrence names one
actorWho caused it: {kind, uuid}, uuid null exactly when kind is system or unattributed. See Actors
subjectThe entity the event is about, as a typed reference
refsOther entities the occurrence names, same shape as subject
detailThe typed payload — varies by event type, see the catalog
dedupe_keyNames this one occurrence. Same value on every retry, different for every occurrence. Dedupe on it — see Delivery. Treat it as opaque; do not parse it
dedupe_discriminatorAn input to dedupe_key, not information. Ignore it
endpointWhich of your endpoints delivered this

Every reference — subject, each of refs, and the ref-shaped fields inside detail — is {kind, uuid, workspace_uuid, org_uuid, account_uuid}. Never an inline name, never a value.

detail always carries type (equal to the envelope's event_type), schema_version, and backfill (true when the row was synthesized from canonical data by a backfill job rather than observed live). The catalog below lists what each type adds.

event_type, visibility, actor.kind, subject.kind and every enum inside detail come from closed sets. Treat an unrecognised value as "ignore, don't error" — these vocabularies grow.

Actors​

actor.kind says who caused the occurrence:

KindMeaning
memberA person in the workspace, including a member acting on their own record
agentAn Agent. Recorded as agent even when it acts through a member session; uuid is the Agent's member id
accountAn account acting without a workspace membership, such as an administrator
org_accountAn organization-scoped account. Reserved: not emitted today
connectionAn app connection. Reserved: not emitted today (a connector sync is system; the event does not name the connection, and a record event from a sync has detail.source_channel sync)
systemNo person or Agent was involved: a schedule, or an inbound carrier or billing event
unattributedSomeone may have acted, but the source does not record who. Only events synthesized by a backfill (detail.backfill is true) carry it, and those are not delivered to webhooks today; the activity feed serves them

A new kind is an additive change: treat one you do not recognise as an unnamed actor. Events recorded before agent attribution and unattributed were introduced are not rewritten, so older events can show an Agent's action as member and a backfilled row as system.

What never arrives​

  • Account-private occurrences. An event reaches an endpoint only by the workspace it rolls up under. Chat events are workspace occurrences, direct messages included — a DM is your team talking to a Member. The exception is a Member's own tool sessions (a manager chat, an agent job chat), which roll up under that account rather than a workspace, so they are not delivered here even when the endpoint's workspaces would otherwise include them. A confirmed outbound send from such a session does deliver message.sent when its recipient is a Member. Its detail then carries no chat and no message_uuid.
  • Org-only events. Billing and domain-verification types exist in the vocabulary but are not deliverable at workspace visibility, so they cannot be subscribed to.
  • Delivery outcomes. A failed delivery is not itself an event. There is no webhook.failed in the vocabulary and there never will be; a delivery outcome cannot be subscribed to.
  • Field-level detail. Deliveries carry identifiers and field slugs, never field values. Read the record back through the API.
  • Test runs, for Task entries and Member messages. assignment.task_entered and member.message_received are not recorded for a test-run Assignment or Chat.
  • Message text. member.message_received names the Member, the Chat, the message uuid and the channel. Read the Chat back for what was said.

Resolving identifiers​

Read the details back with an Organization API key, on the workspace named by workspace_uuid. For calls, voicemails, members and records, a key without the scope below gets 403 whatever the uuid; with it, a uuid you still may not read answers 404, exactly as one that does not exist. A chat you do not own answers 404 in both cases, a missing chats:read included, and direct-message and manager chats are readable only by their participants.

You gotRead it withScope
A member refGET /api/v2/w/{workspace_uuid}/members/by-uuid/{uuid}members:read
A data_record refGET /api/v2/w/{workspace_uuid}/data-types/records/by-uuid/{uuid}records:read
call.completed / call.summary subject, or a data_record.* detail.callGET /api/v2/w/{workspace_uuid}/calls/by-uuid/{uuid} — the response carries chatId and chatUuid. It does not include recordings. A call with no chat (a direct call between two people) is not readable here and answers 404chats:read
detail.recording on call.completed or voicemail.transcribedAn ids-only ref (kind recording, uuid). Calls and voicemails recorded since recording became internal-only have no Recording row, so their events carry null. For call audio, prefer GET /api/v2/w/{workspace_uuid}/calls/by-uuid/{uuid}/download-url in Fetching call audio and transcript. It needs no chatId hop and serves the same unified playback selection as the Chat-keyed routechats:read
A chat ref or subject (e.g. call.summary detail.chat, data_record.* detail.chat, chat.summary)GET /api/v2/w/{workspace_uuid}/chats/by-uuid/{uuid} — the summary is summary / summaryUpdatedAtchats:read
voicemail.received subject (a voicemail)GET /api/v2/w/{workspace_uuid}/voicemails/by-uuid/{uuid}phones:read
detail.member on assignment.task_entered, or the member.message_received subjectGET /api/v2/w/{workspace_uuid}/members/by-uuid/{uuid} — the response carries the Member's labels, so a condition on the Member's labels becomes a check heremembers:read
detail.workflow, detail.task, detail.task_lineage_uuidConfiguration identifiers to match against. Take them from the Workflow in the app; task_lineage_uuid is the one that survives a publish—

Delivery​

MethodPOST
Content-Typeapplication/json
BodyJSON with alphabetically sorted keys, UTF-8
Signature headerX-Webhook-Signature — HMAC-SHA256, see Request signing
Timeout30 seconds total, connection included
RedirectsNot followed
SuccessAny 2xx
RetriesUp to 12 attempts, exponential backoff from 60 seconds, doubling to a 1-hour cap

Deliveries run on a fixed once-a-minute schedule rather than firing the instant the event happens. This is a durable queue, not a live push: a burst of activity is spread across ticks rather than delivered all at once.

4xx is retried. No HTTP status is by itself a permanent rejection — timeouts, connection errors, 3xx, 4xx and 5xx are all retried on the same schedule. Return 2xx as soon as you have durably accepted the payload, and do your processing asynchronously.

At-least-once, not exactly-once. dedupe_key is unique per occurrence: a retry or replay of one occurrence carries the same dedupe_key, and two occurrences never share one — two updates of one record carry two keys. Dedupe your handler on dedupe_key alone. If you already dedupe on the pair of dedupe_key and occurred_at, keep it: occurred_at is also the same on every retry, so the pair identifies exactly the same deliveries.

One exception, for events recorded by the platform build before this guarantee shipped (late September 2026). For some types that can recur on the same subject, such as data_record.updated and journey.enrolled, such an event keeps the key it was recorded with, and that key is shared by the subject's other occurrences recorded before the change. (The member.*_changed types already carried a per-occurrence key and are unaffected.) You can receive one after the change shipped: on a retry or redelivery of an older delivery, or for an occurrence that was still waiting to be processed at deploy time. The pair of dedupe_key and occurred_at separates those events too.

Two failures skip the retry schedule and dead-letter immediately, because retrying cannot fix either: a destination that fails the egress-safety check (the hostname is resolved and the connection pinned to the address actually vetted), and a missing or corrupted signing secret.

When your receiver stays broken​

A delivery dead-letters after 12 attempts. Delivery failures do not pause or disable the endpoint. Other events continue, including after a single delivery exhausts its retries. Unsafe destinations and missing signing secrets still dead-letter immediately; requests never bypass signing or network safety checks.

After 5 failed attempts in a row, Gravity Rail holds the endpoint's queue. New and pending events wait and spend none of their attempts. Gravity Rail retries one delivery a minute later, then at a doubling interval up to once an hour. The first successful delivery releases the queue, and the waiting events are sent in order of arrival. An outage of a few hours therefore delays your events but does not dead-letter them. Saving a change to the endpoint (for example a new URL or signing secret) retries it at once. A timeout, a network error or a 5xx response also stops further sends to your endpoint for the rest of that minute. A 4xx response applies only to the event it answers.

Gravity Rail attempts to warn organization admins and owners when it holds the endpoint or a delivery dead-letters. One failed attempt does not send a warning. Email notices are best-effort. Once the mail provider confirms a warning, reminders are suppressed for 24 hours. When no warning is confirmed, later failures may retry notification after 15 minutes, so an unconfirmed send can result in duplicate mail. The warning names the endpoint, failure classes, retry limits and retention, with a link to Organization → Webhooks. A warning failure does not stop delivery. Inspect failed deliveries, fix the receiver, and replay dead letters when ready. Pause the endpoint yourself if you need to stop sends.

See an endpoint's health in the app or the API. Under Organization → Webhooks, a failing endpoint shows a Failing chip and a held one shows Held, with when the failures began, when the next retry goes, the last error and how many deliveries are waiting. A paused endpoint that is held shows Resume to retry. The same facts are in each endpoint's deliveryHealth (see API).

New events keep queueing during an operator pause or a hold. Pending events expire after 7 days. Previously disabled endpoints remain held until an operator reviews and resumes them; this policy does not automatically replay an old backlog.

Discard a backlog your receiver will keep rejecting. If the held events are malformed for your receiver (for example, after a schema change), discard them before you resume: POST …/deliveries/discard-pending on a paused or disabled endpoint moves every queued delivery to expired. Expired deliveries stay in the log and can still be replayed one at a time. Dead-lettered deliveries are not re-sent on resume and need no clearing.

An endpoint's status is active, paused (an operator's choice) or disabled (a historical automatic disable). Every change, including the initial active, records who made it (null when the system did), why, and when.

Deleting an endpoint stops delivery immediately, but its already-queued deliveries are not deleted with it — they simply age out under the same 7-day retention.

Delivery and attempt rows are an operational troubleshooting log kept for 30 days, not the compliance record. Configuration changes stay in the admin-config audit log and status transitions stay in the status history after delivery details age out.

Request signing​

Every delivery and every test send is signed with HMAC-SHA256 using the endpoint's signing secret:

  • Header: X-Webhook-Signature
  • Format: t={unix_timestamp},v1={hex_digest}. The v1 label names the signature scheme, not the webhook version.
  • Signed message: the ASCII string {timestamp}. followed by the raw JSON body bytes, exactly as sent.
  • Secret: the endpoint's secret from Setting one up. Each attempt is signed at send time, so a retry carries a fresh t.

Reject a request whose timestamp is more than five minutes from your clock (replay protection), and compare signatures in constant time. Verify the raw request body: keys arrive alphabetically sorted, and parsing then re-serializing the JSON changes the bytes.

The TypeScript SDK ships this check as verifyWebhookSignature (with WEBHOOK_SIGNATURE_HEADER and signWebhookPayload for tests) from @gravity-rail/sdk/helpers. It uses Web Crypto, so it runs in Node 18+ and edge runtimes:

import { verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER } from '@gravity-rail/sdk/helpers';

const result = await verifyWebhookSignature(
rawBody,
request.headers.get(WEBHOOK_SIGNATURE_HEADER),
signingSecret,
);
if (!result.ok) return new Response(result.reason, { status: 401 });

Without the SDK, in Python:

import hashlib
import hmac
import time


def verify_webhook(body: bytes, header: str, secret: str, tolerance_sec: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
timestamp, signature = int(parts["t"]), parts["v1"]

if abs(time.time() - timestamp) > tolerance_sec:
return False

message = f"{timestamp}.".encode() + body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature.encode(), expected.encode())

Or in Node.js:

const crypto = require('crypto');

function verifyWebhook(body, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const timestamp = parseInt(parts.t, 10);
const signature = parts.v1;

if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;

const message = Buffer.concat([Buffer.from(`${timestamp}.`), body]);
const expected = crypto.createHmac('sha256', secret).update(message).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Testing​

Every endpoint has a Send test event action (⋯ menu on the endpoint card). Pick an event type, and you get the real payload for it, filled with example identifiers. Edit anything you like — put in an id your handler will actually resolve, drop a field to see what your parser does without it — and send. You get back the HTTP status, how long it took, and your own server's reply body.

The test goes through exactly the same delivery code a real send does: the same egress vetting, the same address pinning, the same canonicalization, the same HMAC, the same outcome classification. A successful test shows that a correctly signed request reached your receiver and that it returned a 2xx. It does not prove your handler parsed the payload or acted on it — a stub, proxy or handler that early-returns without reading the body also answers 2xx; your handler's logs or the reply body the test returns are what show processing. It does not prove your handler verifies the signature either — a receiver that ignores X-Webhook-Signature also returns 2xx; only seeing it reject a deliberately bad signature shows that. It also does not show that live activity emits the event types you expect or that the endpoint's workspace scope matches that activity: a test emits no event and does not match the event against endpoint coverage.

To confirm your receiver verifies the signature, send it a request yourself with a deliberately wrong X-Webhook-Signature header and check that it answers 4xx. The test send always signs with the stored secret, so it can show that a correct signature is accepted, not that a bad one is rejected.

To verify live emission for record events, endpoint scope, and delivery together, make a synthetic create or update on an opted-in test Form in a workspace the endpoint covers, then confirm the resulting event appears in the endpoint's delivery log. That path exercises the real event matching and delivery; the test send cannot. Record events need the per-Form opt-in; for other event types, real activity in a covered workspace is required.

That synthetic event is a normal live delivery with no "test": true marker, so treat it as real: send it to a receiver that tolerates a test record, and expect the endpoint's other consumers — a CRM, an analytics pipeline, any workspace automation — to process it too. The endpoint must also be active; a paused or disabled endpoint records the event in its log, but the delivery waits until the endpoint is resumed.

What it deliberately does not do:

  • It queues nothing. No delivery row, no attempt, no retry.
  • It does not change endpoint status or consume a queued delivery's retry budget. Test failures do not trigger delivery-failure warnings.
  • It does not fill your delivery log, so the log stays useful for diagnosing real traffic.

It works on a paused or disabled endpoint too — those states hold the queue back, and "is it fixed yet?" is exactly the question you have while an endpoint is paused.

The delivered body carries "test": true at the top level. It is in the body rather than a header on purpose: the signature covers the body, so a receiver that wants to discard test traffic can key on a value it has verified.

The event-type picker lists the types this endpoint is subscribed to, with find-as-you-type narrowing. To try a handler against a type before you commit to the subscription, subscribe to it, test, then unsubscribe — the test send itself never changes the subscription.

The direct test API is wider than the UI picker: POST .../test still accepts any event type in the closed subscribable vocabulary, subscribed or not. The picker narrows the offer; the API keeps the contract.

Reading a field value after a data_record.* webhook​

A data_record.created or data_record.updated delivery tells you which fields were written, never what they were set to. To act on a value, such as sending an email when a date field is filled in, your handler verifies the delivery, checks the slug, and reads the record back.

detail.source_channel says how that write happened. It is not a call.

ValueThe write
web_formA signup, or a public Site form (CCM enrollment). A records API call outside a Site session is api
voiceAn Agent wrote the record during a voice chat
smsAn Agent wrote the record during SMS
apiThe records API, an import, or a member upsert
managerAn Agent or the app, and not a phone call or SMS
syncA connector sync
systemA rule, a backfill, or a write that did not name a channel

actor.kind of agent means a machine principal. A field slug is a schema name, including a slug that contains "call". Calls are the call.* and voicemail events. The activity API spells this field sourceChannel. Organization webhook deliveries spell it source_channel.

Before you start:

  • The Form has record events turned on (webhook_events_enabled). See the catalog note.
  • Your endpoint subscribes to data_record.updated, plus data_record.created if the field can be set when the record is created, and covers the workspaces involved.
  • The Form's records are written through a surface that emits. Some connector sync writes emit and some do not (see the catalog note); check yours before you rely on it.
  • You have an Organization API key with records:read, plus members:read if you also need the owning Member. Send it as Authorization: Bearer <key>. Values come from Forms that hold PHI, so read Data use and PHI before you design around an organization key.

1. Verify the signature against the raw body​

Use the Request signing verification code unchanged, with your endpoint's signing secret from Setting one up. It checks the X-Webhook-Signature: t=…,v1=… header, the HMAC-SHA256 over {t}. plus the raw body, and the five-minute window. Verify the bytes exactly as they arrived. Do not parse the JSON and serialize it again first. Each attempt is signed at send time, so a retry carries a fresh t.

2. Check that the delivery names your field​

Read event_type, detail.field_slugs and detail.data_type. The slugs are the Form's field slugs in snake_case, sorted:

  • On data_record.created, they are every declared field the new record stored.
  • On data_record.updated, they are the fields that write changed. An update that does not touch your field does not list it.
  • The list can be empty on an update whose writer could not say which fields moved. Treat empty as "may have changed" if you cannot afford to miss one.

A field rename does not emit a record event, and it does not change deliveries already sent. Those keep the slug they were recorded with. The next create or update that touches the field lists the new slug in field_slugs. Update your mapping to that slug. The rename preview reports Gravity Rail references that still use the old slug (expressions, prompts, saved queries, connector maps). It does not see a mapping that lives in your receiver.

A delivery whose list does not contain your slug needs no read. Return 2xx and stop. Deliveries with "test": true at the top level come from Send test event and name example IDs.

3. Deduplicate, and accept fast​

Record dedupe_key before you do any work, and skip one you have already processed. It is unique per occurrence, so every update of a record has its own (see Delivery). Return 2xx once you have durably accepted the delivery. Every non-2xx, including 4xx, is retried for up to 12 attempts, so fetch and process asynchronously.

4. Fetch the record by UUID​

subject.uuid is the record; workspace_uuid is where it lives.

curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/data-types/records/by-uuid/$RECORD_UUID"
{
"id": 4182,
"uuid": "0b7f6a52-3c1e-4d2a-9f4b-6e8d1c2a7b90",
"dataTypeId": 7,
"memberId": 9051,
"memberName": "…",
"fieldValues": { "follow_up_date": "2026-09-23", "…": "…" },
"createdAt": "2026-09-20T15:02:11.410000Z",
"updatedAt": "2026-09-23T17:44:05.918000Z",
"externalId": null,
"accessMode": null,
"retirement": null
}
StatusMeaning
200The record. fieldValues is keyed by field slug
403The key lacks records:read
404Not readable by this key, deleted since the event, or never existed. These cases are deliberately indistinguishable. Do not retry forever

The response is the record now, not a snapshot from when the event was recorded. Deliveries are not ordered, and a later write may have landed first. Reading the current value is what keeps an out-of-order delivery harmless. Compare updatedAt if you need to tell whether you have already acted on this state.

A field marked admin-only on the Form is left out of fieldValues unless the key also holds records:admin. A field that was never set is usually absent rather than null, so handle both.

5. Read the value and the owning Member​

fieldValues[<slug>] is the value. On a member-scoped Form, memberId is the owning Member's integer id. Read the Member with it:

curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/members/$MEMBER_ID"

The Member response carries uuid and externalId, plus contact fields. Store the identifier you join on, not the contact details. memberId is null for a record with no owner.

Date and time values​

Field typeStored and returned asExample
dateAn ISO 8601 calendar date. No time, no timezone"2026-09-23"
datetimeISO 8601, with an offset only when the writer supplied one"2026-09-23T14:30:00+00:00"

A date is a calendar day as the writer recorded it. The platform does not convert it to a timezone. Render it as a plain date. Do not parse it as midnight UTC, because new Date("2026-09-23") in JavaScript is midnight UTC and prints as the 22nd anywhere west of Greenwich. A datetime without an offset has no timezone, so do not assume one.

Example handler (Node.js)​

const express = require('express');
const crypto = require('crypto');

const app = express();
const FIELD = 'follow_up_date';
const API = 'https://api.gravityrail.com/api/v2/w';

// verifyWebhook: the function from Request signing (#request-signing)

app.post('/gravity-rail', express.raw({ type: 'application/json' }), async (req, res) => {
if (!verifyWebhook(req.body, req.get('X-Webhook-Signature') || '', process.env.GR_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
const slugs = event.detail?.field_slugs ?? [];
if (event.test || !event.event_type.startsWith('data_record.') || !slugs.includes(FIELD)) {
return res.sendStatus(204);
}
const isNew = await markSeen(event.dedupe_key); // your durable store
res.sendStatus(202);
if (isNew) enqueue(() => handleRecord(event.workspace_uuid, event.subject.uuid));
});

async function handleRecord(workspaceUuid, recordUuid) {
const headers = { Authorization: `Bearer ${process.env.GR_API_KEY}` };
const r = await fetch(`${API}/${workspaceUuid}/data-types/records/by-uuid/${recordUuid}`, { headers });
if (r.status === 404) return; // deleted, or not readable by this key
if (!r.ok) throw new Error(`record read failed: ${r.status}`); // let your queue retry
const record = await r.json();
const value = record.fieldValues[FIELD]; // "YYYY-MM-DD", or undefined if unset
if (value === undefined || value === null || record.memberId == null) return;
const m = await fetch(`${API}/${workspaceUuid}/members/${record.memberId}`, { headers });
if (!m.ok) throw new Error(`member read failed: ${m.status}`);
const member = await m.json();
// Act on (member.uuid, value). Treat the value as a plain calendar date.
}

Fetching call audio and transcript​

A call event names the Call, not the media. Use its Call UUID directly for audio. A data_record.* event written by the call also carries detail.call.uuid; call.started, call.completed, call.missed and call.summary carry the same UUID as subject.uuid.

Audio: request a short-lived presigned URL for the whole call as one WAV file, then download it. No Chat ID lookup is needed:

# Get a presigned download URL for the call recording (optional expires_in, in seconds)
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/calls/by-uuid/$CALL_UUID/download-url"

# Download the WAV from the returned downloadUrl before it expires
curl -o "call-$CALL_UUID.wav" "$DOWNLOAD_URL"

The response carries downloadUrl, expiresIn and mimeType (audio/wav). The route needs chats:read and applies the Call's Chat access policy. A 404 means the Call is unavailable under that policy or it has no playable recording (recording was off, the Call was too short, or the recording is incomplete or still in progress). The complete edge capture is preferred; older stored recording formats use the same route and response. Existing code can keep using recordings/chat/{chat_id}/download-url; the CLI equivalents remain gr recordings download-url and gr recordings download.

Transcript and Chat metadata: read the Call with GET /api/v2/w/{workspace_uuid}/calls/by-uuid/{uuid} to get its chatId and chatUuid, then read its Messages with chats:read:

curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/chats/$CHAT_ID/messages"

This keeps PHI off the webhook channel: the payload carries only identifiers, and the audio and transcript travel over authenticated requests you initiate.

CCM enrollment​

This is the receiver contract for the ccm_enrollment Form. Subscribe to data_record.created and data_record.updated, and to call.queued, call.started, call.completed, call.missed, call.not_placed, call.summary, voicemail.received, and voicemail.transcribed if you also handle voice. The Form must have record events turned on. One save produces one record event. A save that changes nothing produces none.

MomentWhat you receive
First Site submit that creates the recordOne data_record.created. detail.source_channel is web_form. detail.field_slugs is the slugs that submit stored, sorted. occurred_at is the database time of that write
A later Site submit that changes one or more fieldsOne data_record.updated for the slugs that changed, source_channel web_form
A Site submit whose values already match the recordNo record event
A practice rule that then stamps enrollment_date and consent_timestampA separate data_record.updated, source_channel system, slugs consent_timestamp and enrollment_date. That is the rule, not a second copy of the form
An automated call is accepted into the paced call queuecall.queued on the Chat. Queued is not ringing
A queued call is not placedcall.not_placed on the Chat. detail.reason is admission_timed_out when its deadline passed while it waited, or expired when it was admitted but stopped before the call was made (its reservation lapsed or could not be used, or its calling window closed). An expired one follows a call.started for the same outbound_call_intent, and that call row also ends with call.missed (reason rejected). No call was made: call.not_placed is the outcome to act on, so do not count that call.missed as a missed call
A voice or browser call startscall.started when the call row is created
A connected call endscall.completed
A call never connectscall.missed
An Agent writes the record during a phone calldata_record.created or data_record.updated with source_channel voice, detail.chat naming that voice chat, and detail.call naming its call. A browser voice session has no call row, so it carries chat and a null call
An Agent writes it during SMSsource_channel sms, detail.chat naming the SMS chat, no call
Pathways confirms a first appointment the Agent bookeddata_record.updated, slug first_appointment. source_channel follows the chat the Agent was in

A web-form enrollment does not emit call.*. A voice call does not label the record write web_form.

source_channel is how this write happened. enrollment_channel is a field on the record (web_form, voice_conversation, or care_team) and is not in the webhook. Fetch the record to read it. The two agree on a Site submit. A later API edit keeps the stored enrollment_channel and reports source_channel api. actor.kind of agent, and a slug that contains "call", do not mean a call happened.

Correlating a disposition with its call​

detail.chat and detail.call are how a disposition binds to the call it belongs to. They are ids-only refs: chat is the chat the write happened in, and call is that chat's latest phone leg, the same call call.summary names for the chat. Resolve the chat with chats/by-uuid and the call with calls/by-uuid (Resolving identifiers).

Both are null on a write that happened outside a chat: a Site submit, an API edit, a connector sync. They are also both null when the write happened in an account-private chat — a manager or agent-job session — whose existence a webhook never discloses. The record event itself still arrives; only the two refs are withheld.

The authoritative chat is the one the write happened in. When a patient has several calls, a record event names the chat that produced that write — never a chat chosen afterwards by call duration, recency or ring count. The same rule bounds the reverse: a record touched by two calls carries two writes, each with its own chat. Ordering is not guaranteed: an enrollment outcome may arrive before or after the owning call.completed or call.summary, so bind by chat.uuid rather than by arrival order. call.completed carries no chat ref of its own; calls/by-uuid maps the call to its chatId and chatUuid, and call.summary detail.chat names the chat directly.

Do not read a null chat on a voice_conversation record as normal. A write the Agent performs during the call names its chat whenever that chat is resolvable — it is withheld for an account-private chat, a chat deleted before the event was written, or a malformed chat id; otherwise null means the write did not come from the call, or predates this field.

Enrollment fields​

Slugs for ccm_enrollment. The webhook lists slugs only. Values are on the record, from step 4. Examples below are fictional.

SlugLabelTypeExampleMeaning
enrollment_channelEnrollment Channelenum: voice_conversation, web_form, care_teamweb_formChannel the patient enrolled through. The Site writes web_form
visit_mediumVisit Mediumenum: sms, emailsmsHow they opened the enrollment link. Absent when the link had no medium
call_statusCall Statusenum: reached, not_available, callback_requested, left_messagecallback_requestedWhether they were reached. Callback requested is this value, not its own field
callback_dateCallback Datedatetime2026-10-14T15:00:00-04:00Time they asked to be called. Not a confirmed booking. Keep the offset
first_appointmentFirst Appointmentdatetime2026-10-16T14:30:00-04:00First coordinator call, with its offset. A Site submit writes the time the patient picked before Pathways is asked to book it, so a Site-written value is a requested time. An Agent writes it only after Pathways confirms
call_notesCall Noteslong textPrefers a call after lunch.Notes from the enrollment call. There is no field named notes
enrollment_statusEnrollment Statusenum: enrolled, follow_up, declined, pending, digital_outreach_completedenrolledDecision recorded on the form. digital_outreach_completed means the text and email outreach sequence ended with no decision from the patient
enrollment_dateEnrollment Datedatetime2026-10-14T18:02:11.483920+00:00Instant consent was recorded, with its offset. Written once by a rule, in the same write as consent_timestamp. Not written by the Site submit itself. Convert it to UTC or a local date yourself. The offset follows the workspace timezone, which is UTC when none is set. The workspace's Form sets the type: before 2026-10-20 this was a date, and a workspace that has not moved to datetime still returns YYYY-MM-DD
identity_verifiedIdentity VerifiedbooleantrueName and date of birth were accepted for this session
consent_givenConsent GivenbooleantrueConsent to enroll
consent_timestampConsent Timestampdatetime2026-10-14T18:02:11.484102+00:00Instant consent was recorded. Set whenever enrollment_date is set, by the same rule. It can differ from enrollment_date by a millisecond. Not written by the Site
text_reminders_opted_inText Reminders Opted InbooleantrueOpt-in for care-coordinator text reminders
sms_phone_numberSMS Phone Numberphone+15555550199Set only when text reminders are on. Cleared when they opt out
contact_phoneContact phonetext+15555550199Number they typed. Not verified
contact_emailContact emailtextada@example.comAddress they typed. Not verified
email_consentEmail consentbooleanfalseAgreed to email contact
decline_reasonDecline Reasonlong textNot at this time.Why they declined
cost_disclosure_typeCost Disclosure Typeenum: out-of-pocket, co-insurance, nonenoneWhich cost disclosure was given
visit_sourceVisit Sourcetextspring-mailerCampaign or referral on the link
authority_to_consentAuthority to Consentenum: patient_self, caregiver_spouse, caregiver_non_spousepatient_selfWhose authority the consent rests on
consenting_partyConsenting PartytextAda LovelaceName of the person who gave consent: the patient, or the caregiver consenting for them
poa_verbally_confirmedPOA Verbally Confirmedenum: yes, noyesCaregiver path only: the caregiver's answer on the call when asked whether they hold healthcare decision authority. Absent when the patient consents for themselves

There is no care-coordinator slot field. The Site shows Pathways availability windows and, when the patient picks a start, stores that instant on first_appointment. After the record is written, the Site asks Pathways to book that time. The booking outcome is not on the record. Provider ids from those windows are not on the record and are not in the webhook.

Recordings and transcripts​

Webhooks never include field values, message text, transcripts, or audio. call.completed and voicemail.transcribed may carry detail.recording, an ids-only ref, or null when no recording row exists (always, for calls and voicemails recorded since recording became internal-only). Fetch call audio directly by Call UUID with GET .../calls/by-uuid/{uuid}/download-url, as in Fetching call audio and transcript. Read the Call with GET .../calls/by-uuid/{uuid} only when you also need chatId / chatUuid for the transcript or Chat metadata.

Example payloads​

Identifiers only. The same fictional workspace and organization as the payload example. A real delivery's keys are sorted alphabetically; these are shown expanded so they are readable.

A Site enrollment create. dedupe_key is opaque. It names this write, so a retry keeps the same key and the same occurred_at. Ignore dedupe_discriminator.

{
"id": "6c87845e-73e3-538a-9e9b-a197023cf884",
"occurred_at": "2026-10-14T18:02:11Z",
"event_type": "data_record.created",
"event_version": 1,
"visibility": "workspace",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": "3c8c25ca-c126-52f7-8a1b-3a40ba93c609",
"account_uuid": null,
"actor": { "kind": "member", "uuid": "5ec1da83-d1c9-5aa7-849c-a6fcb0d18631" },
"subject": {
"kind": "data_record",
"uuid": "0b7f6a52-3c1e-4d2a-9f4b-6e8d1c2a7b90",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": null,
"account_uuid": null
},
"refs": [],
"detail": {
"schema_version": 1,
"backfill": false,
"type": "data_record.created",
"source_channel": "web_form",
"field_slugs": ["callback_date", "consent_given", "contact_phone", "enrollment_channel", "enrollment_status", "identity_verified", "text_reminders_opted_in"],
"data_type": {
"kind": "data_type",
"uuid": "7a1c0e44-2b8d-4f61-9c33-1e5d8a0b6c42",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": null,
"account_uuid": null
},
"chat": null,
"call": null
},
"dedupe_discriminator": { "kind": "e", "entity": "4f8a1c20-6d3e-4b7a-9f11-2c5e8a0d7b64", "ordinal": null, "instant": null },
"dedupe_key": "data_record.created:data_record:0b7f6a52-3c1e-4d2a-9f4b-6e8d1c2a7b90:e:4f8a1c20-6d3e-4b7a-9f11-2c5e8a0d7b64",
"endpoint": { "uuid": "9c1f7e5a-1b2c-4d3e-8f90-a1b2c3d4e5f6", "name": "Enrollment postback" }
}

A confirmed appointment written during a voice call:

{
"event_type": "data_record.updated",
"occurred_at": "2026-10-14T18:16:40Z",
"actor": { "kind": "member", "uuid": "5ec1da83-d1c9-5aa7-849c-a6fcb0d18631" },
"subject": { "kind": "data_record", "uuid": "0b7f6a52-3c1e-4d2a-9f4b-6e8d1c2a7b90" },
"detail": {
"schema_version": 1,
"backfill": false,
"type": "data_record.updated",
"source_channel": "voice",
"field_slugs": ["first_appointment"],
"chat": {
"kind": "chat",
"uuid": "48a08390-1c63-498b-aa5c-b0362e532d95",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": null,
"account_uuid": null
},
"call": {
"kind": "call",
"uuid": "11aa22bb-33cc-44dd-55ee-66ff77889900",
"workspace_uuid": "5099b28c-b8f0-5d8f-9ea9-2d077cb89af3",
"org_uuid": null,
"account_uuid": null
}
}
}

The other envelope fields match the create above. source_channel voice is the call, including when actor.kind is member: the dispatch records the record's owner. source_channel manager is an Agent or the app, and not a phone call or SMS. chat and call are populated only when the write happened in a conversation; both are null on the Site submit above and on an API edit.

A connected call ending. Audio is not in this body. The catalog lists every call field.

{
"event_type": "call.completed",
"subject": { "kind": "call", "uuid": "11aa22bb-33cc-44dd-55ee-66ff77889900" },
"detail": {
"schema_version": 1,
"backfill": false,
"type": "call.completed",
"direction": "outbound",
"outcome": "completed",
"duration_ms": 186000,
"recording": {
"kind": "recording",
"uuid": "22bb33cc-44dd-55ee-66ff-77889900aabb"
}
}
}

recording is null on call.completed for calls recorded since recording became internal-only: the internal recorder writes no recording row. Fetch the audio later with the chat id.

Failed HTTP attempts, including timeouts and 5xx responses, retry with backoff. After 12 attempts, that delivery becomes a dead letter. The endpoint stays active and other events continue. Admins receive failure warnings. See When your receiver stays broken.

API​

RouteWhat it does
GET/POST /api/v2/o/{org_uuid}/webhooksList and create endpoints
GET/PATCH/DELETE /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}Read, update, delete one
GET /api/v2/o/{org_uuid}/webhooks/event-typesThe closed subscribable vocabulary
GET /api/v2/o/{org_uuid}/webhooks/event-types/{event_type}/sampleA representative payload for one type
POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/testSend one payload now; returns the outcome
GET /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveriesDelivery history. Optional status (pending, processing, sent, dead_letter, expired), occurredAfter (inclusive) and occurredBefore (exclusive, timezone-aware timestamps) filters apply before limit/offset. total counts the filtered results
POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveries/{delivery_id}/replayRe-queue one failed or expired delivery, including a failed pending delivery waiting for retry. Refused with 409 unless the endpoint exists and is active
POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveries/discard-pendingMove every queued (pending) delivery to expired; returns {"discarded": n}. Body {}. Refused with 409 while the endpoint is active
GET /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveries/{delivery_id}Admin-only, audited request and response inspection. New diagnostics are retained for 30 days; response previews are bounded to 16 KB
POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveries/clearBody {"failedOnly": true} clears failed history; false clears all history. Cancels selected pending retries, retains delivery identity, and leaves in-progress sends visible. Available at any endpoint status
GET /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/coverageWhich covered workspaces have a Form opted in to record events
GET /api/v2/w/{workspace_uuid}/webhook-logs/org-endpointsFrom inside a workspace: which org endpoints it feeds
GET/POST /api/v2/o/{org_uuid}/workspace-labelsList and create workspace labels
PATCH/DELETE /api/v2/o/{org_uuid}/workspace-labels/{label_uuid}Rename or recolor; delete (409 while a webhook endpoint, organization API key or org Agent selects on it — webhookSelectorCount, apiKeySelectorCount, agentSelectorCount)
GET/PUT /api/v2/o/{org_uuid}/workspaces/{workspace_uuid}/labelsRead or replace one workspace's labels (unknown slugs create labels)
POST /api/v2/o/{org_uuid}/workspace-labels/preview-scopeWhich workspaces a scope reaches now

Notes on the shapes:

  • Coverage is one object, workspaceScope, the same one organization API keys and org Agents use. Send it as {"mode": "all"}, {"mode": "none"}, or {"mode": "selected", "workspaceUuids": [...], "labelSelector": [...]}. selected needs at least one workspace or label; all and none take neither list. Both mistakes are a 422: the mode is never inferred from empty lists. Send labelSelector as label slugs; each must be an existing label of your organization, and each workspace must be one of its workspaces (otherwise 400). workspaceUuids takes at most 100 entries and labelSelector at most 10; a longer list is a 422.

  • Create requires workspaceScope. On update, omitting workspaceScope leaves coverage unchanged; sending it replaces the whole selection — mode, workspaces and labels — so {"mode": "none"} stops all delivery. The former top-level workspaceUuids, labelSelector and limitedToWorkspaces fields are refused with 422.

  • Endpoint reads return workspaceScope with mode, workspaceUuids (sorted) and labelSelector as label summaries (uuid, slug, name, color). mode is read from what is stored: a selected endpoint whose last workspace was deleted and that has no labels reads none and covers nothing.

    "workspaceScope": {
    "mode": "selected",
    "workspaceUuids": ["5099b28c-b8f0-5d8f-9ea9-2d077cb89af3"],
    "labelSelector": [
    { "uuid": "3f0c7a1e-8d2b-4c6a-9e1f-2b7d5a9c4e10", "slug": "production", "name": "Production", "color": "16a34a" }
    ]
    }
  • POST /api/v2/o/{org_uuid}/workspace-labels/preview-scope takes the same workspaceScope object as its body (for example {"mode": "selected", "labelSelector": ["production"]}) and returns workspaceCount — how many workspaces it reaches right now — and the first few by name. none reaches zero.

  • Each endpoint carries statusHistory, most recent first, up to 20 entries.

  • Each endpoint carries recentFailures: the failure classes (failureClass, count) of its dead-lettered deliveries in the last 24 hours, counted from the latest activation when that is newer. Historical failures age out even while an endpoint remains disabled; statusHistory records why it stopped.

  • Each endpoint carries deliveryHealth:

    • state: healthy, failing (attempts are failing, events still flow) or held (Gravity Rail holds the queue and retries one delivery at nextProbeAt). An endpoint with no recorded attempt is healthy with lastSuccessAt: null.
    • consecutiveFailures: failed attempts in a row, across deliveries.
    • failingSince: the first failure of the current run; null while healthy.
    • lastSuccessAt, lastFailureAt, lastFailureClass (network, http_4xx, http_5xx, unsafe_target, missing_secret or retryable).
    • nextProbeAt: set only while held. A paused endpoint sends no retry until you resume it.
    • pendingDeliveries: events not yet sent that can still be sent (inside the 7-day pending window).
  • Endpoint reads return a destination fingerprint (scheme://host plus a short digest of the full URL) rather than the URL — webhook paths and queries routinely carry per-tenant tokens. The full URL is returned only in the create response, like the one-time secret.

  • The delivery log pairs each delivery (event type, when it occurred, its dedupe key, its workspace, queue status, when it next retries) with every attempt made at it, oldest first (attempt number, start and finish, outcome, failure class and error type, HTTP status). Each delivery includes replayable, which reports whether the row can currently be retried. The replay route checks eligibility again when it receives the request.

  • The workspace-side read shows name, destination fingerprint, status, event types and workspaceScopeMode (all, or selected when the workspace is reached through the endpoint's selection; never the other selected workspaces or labels) — never the signing secret, never delivery contents. It is available to any member holding webhooks:read, not only admins.

Event catalog​

data_record.created and data_record.updated are emitted (GRA-8876), but only for a Form that has opted in. The opt-in is the per-DataType webhook_events_enabled setting, off by default: a record write in a Form that has not opted in produces no event at all — not a row that is later filtered — so an endpoint subscribed to these types receives nothing from that Form. Turn it on per Form before relying on record events.

Which surfaces emit, today. Records written through the REST API, the AI data tools, CSV/import, and signup reach the shared post-commit emitter, so an opted-in Form's writes from those surfaces publish. A Site Form uses the ordinary REST create route. Connector syncs emit for these writes: Monday record boards (the scheduled poll and Monday's own webhook), eCW and athenahealth patient profile and Condition records, and new eCW care-plan items. Each event is sent only after the sync's write is saved, as actor.kind system with detail.source_channel sync, and runs no Action. An unchanged re-sync, and a re-link that only changes the record's external ID, send nothing. Directories (shared lookup lists such as CRM owners), connector-managed Member fields and eCW care-plan item updates do not emit; do not rely on data_record.* for a Form whose rows only those writes change. See Data record events in the migration guide.

The payload is IDs and field slugs, never field values: subject names the data_record, detail.data_type names the Form, and detail.field_slugs lists the slugs that were written or changed. A record's values are where its PHI lives, so a consumer that needs contents reads the record back through the API under its own authorization. For how this maps from the retired v1 data-record rules, see Data record events in the migration guide.

chat.summary and call.summary are emitted, and they carry no content. They signal that a summary was persisted: chat.summary for a Chat on any channel, call.summary for a phone-channel Chat only. The envelope names the Chat (chat.summary) or the call (the Chat's most recent PhoneCall, for call.summary) as subject, and the detail carries the channel plus, for the call type, the Chat reference when its identifier is a UUID. The summary text is PHI and is deliberately never in the payload; a receiver that needs it reads the Chat back through the API under its own authorization. Both types are unconditional — there is no per-Chat opt-in.

message.sent fires once for each outbound message to a member, when the send is confirmed: the SMS or WhatsApp provider accepted the text, the email provider accepted the email, or the voice Agent spoke a turn. It covers conversation replies and campaign sends alike, including Journey and rule texts that belong to no Chat. The subject is the recipient member. The detail carries the channel (sms, whatsapp, email or voice), the chat when the send belongs to a workspace-visible Chat, and the message_uuid when the send delivered a message in that Chat. The payload carries no message text. To read the message, fetch the Chat by its uuid through the API under your own authorization. Verification codes and staff approval requests are not member touchpoints and do not emit this event. Deduplicate on dedupe_key: a retried confirmation of one send has the same key.

Removed field. call.completed's detail.recorded boolean was removed when the Twilio-native recording pipeline was deleted. It was true only for calls with a ready Twilio-native recording and cannot be derived from the internal recorder at call-completion time, so a v2 consumer reading it now sees the key absent rather than false. Consumers that branched on it should request GET /api/v2/w/{workspace_uuid}/recordings/chat/{chat_id}/download-url once the call has ended instead: it answers 404 when the Chat has no playable recording.

Voicemail has two arrival events, and they fire at different moments. voicemail.received fires when the caller is sent to voicemail, before anything has been recorded — right for an inbox badge, too early to read the voicemail back. voicemail.transcribed fires once the voicemail's transcription has resolved, with detail.outcome saying how: completed means there is a recording and a transcript to read; failed means transcription failed or the recording never arrived, so there may be nothing to fetch. Subscribe to voicemail.transcribed if you fetch the voicemail on receipt. The transcript itself is never in the payload.

assignment.task_entered fires each time a Member's Assignment enters a Task, for every Task type. Entering the same Task twice gives two events. subject is the Assignment; detail.task is the Task row in the revision the Assignment runs, and detail.task_lineage_uuid is that Task's identity across publishes, so match a specific Task on the lineage. detail.member, detail.workflow, detail.revision_number and detail.chat name the rest. There is no Task name in the payload.

member.message_received fires once for every Member message persisted on a workspace Chat, on every channel, whether or not the Agent took a turn. It is the inbound pair of message.sent and has the same shape: subject is the Member who wrote the message, detail.chat the Chat and detail.message_uuid the message. detail.assignment, detail.workflow and detail.task name the Workflow run the Chat belongs to (absent on a direct message); filter on detail.workflow to keep only Workflow Chats. There is one event per inbound message, so expect volume on the scale of your inbound traffic. Manager and agent-job chats record none, and the text is never in the payload.

A call that never connected — no answer, timeout, rejected, sent to voicemail — ends as call.missed, not call.completed. Subscribe to both to see every ending. call.completed detail does not include recorded. A delivery that still carries that key can be ignored.

There are 53 subscribable event types, in six families. Every one delivers the envelope described above; what changes between them is subject and detail.

People​

Who is in a workspace and what is recorded about them — the member lifecycle, role and label changes, attribute edits, and the imports that do all of those in bulk.

member.created​

subject is a member reference.

detail fieldTypeAlways present
originMemberOriginno
connectionentity refno
accountentity refno
capabilitieslist of ActivityCapabilityno
requested_byentity refno

member.removed​

subject is a member reference.

detail fieldTypeAlways present
reasonMemberRemovalReasonyes
accountentity refno

member.role_changed​

subject is a member reference.

detail fieldTypeAlways present
accountentity refno
capabilitieslist of ActivityCapabilityno

member.labels_changed​

subject is a member reference.

detail fieldTypeAlways present
addedlist of entity refno
removedlist of entity refno

member.attributes_changed​

subject is a member reference.

detail fieldTypeAlways present
field_slugslist of stringno
data_typeentity refno

import.started​

subject is a import reference.

detail fieldTypeAlways present
sourceImportSourceyes
connectionentity refno
expected_rowsintegerno

import.completed​

subject is a import reference.

detail fieldTypeAlways present
sourceImportSourceyes
connectionentity refno
created_countintegerno
updated_countintegerno
skipped_countintegerno
failed_countintegerno
duration_msintegerno

data_record.created​

subject is a data_record reference.

detail fieldTypeAlways present
is_testbooleanno
field_slugslist of stringno
data_typeentity refno
source_channelRecordSourceChannelno
chatentity refno
callentity refno

data_record.updated​

subject is a data_record reference.

detail fieldTypeAlways present
is_testbooleanno
field_slugslist of stringno
data_typeentity refno
source_channelRecordSourceChannelno
chatentity refno
callentity refno

Conversations​

Every exchange with a person, in any channel: chats, escalations, calls, voicemail, and a Member's run through a Workflow (an Assignment).

assignment.started​

subject is a assignment reference.

detail fieldTypeAlways present
workflowentity refno
revision_numberintegerno
triggerAssignmentTriggerno

assignment.concluded​

subject is a assignment reference.

detail fieldTypeAlways present
workflowentity refno
outcomeAssignmentConclusionyes
task_countintegerno
completed_task_countintegerno
duration_msintegerno

assignment.task_entered​

subject is a assignment reference.

detail fieldTypeAlways present
taskentity refyes
task_lineage_uuiduuidno
workflowentity refno
revision_numberintegerno
memberentity refno
chatentity refno

chat.started​

subject is a chat reference.

detail fieldTypeAlways present
laneChatLaneyes
channelChatChannelyes
initiated_byActorKindyes
requested_byentity refno
assistantentity refno

chat.awaiting_human​

subject is a chat reference.

detail fieldTypeAlways present
reasonslist of ChatAttentionReasonyes
cleared_reasonslist of ChatAttentionReasonno
is_testbooleanno

chat.human_replied​

subject is a chat reference.

detail fieldTypeAlways present
cleared_reasonslist of ChatAttentionReasonno
waited_msintegerno
reply_message_uuiduuidno
reply_memberentity refno

chat.call_ended​

subject is a chat reference.

detail fieldTypeAlways present
reasonslist of ChatAttentionReasonno
cleared_reasonslist of ChatAttentionReasonno

chat.auto_replied​

subject is a chat reference.

detail fieldTypeAlways present
reasonslist of ChatAttentionReasonno
cleared_reasonslist of ChatAttentionReasonno

chat.summary​

subject is a chat reference.

detail fieldTypeAlways present
channelChatChannelyes

message.sent​

subject is a member reference.

detail fieldTypeAlways present
channelChatChannelyes
chatentity refno
message_uuiduuidno

message.send_failed​

subject is a workspace reference.

detail fieldTypeAlways present
channelChatChannelyes
failure_classMessageSendFailureClassyes
countintegerno

member.message_received​

subject is a member reference.

detail fieldTypeAlways present
channelChatChannelyes
chatentity refno
message_uuiduuidno
assignmententity refno
workflowentity refno
taskentity refno

escalation.opened​

subject is a escalation reference.

detail fieldTypeAlways present
reasonEscalationReasonyes
chatentity refno
is_testbooleanno

escalation.resolved​

subject is a escalation reference.

detail fieldTypeAlways present
resolutionEscalationResolutionyes
open_msintegerno
chatentity refno

call.started​

subject is a call reference.

detail fieldTypeAlways present
directionCallDirectionyes
phone_numberentity refno
outbound_call_intentuuidno
requested_byentity refno
assistantentity refno

call.completed​

subject is a call reference.

detail fieldTypeAlways present
directionCallDirectionyes
outcomeCallCompletionDispositionyes
duration_msintegerno
phone_numberentity refno
recordingentity refno

call.missed​

subject is a call reference.

detail fieldTypeAlways present
directionCallDirectionyes
reasonMissedCallReasonyes
phone_numberentity refno

call.summary​

subject is a call reference.

detail fieldTypeAlways present
channelChatChannelyes
chatentity refno

call.queued​

subject is a chat reference.

detail fieldTypeAlways present
outbound_call_intentuuidyes
requested_byentity refno

call.not_placed​

subject is a chat reference.

detail fieldTypeAlways present
outbound_call_intentuuidyes
reasonCallNotPlacedReasonyes

voicemail.received​

subject is a voicemail reference.

detail fieldTypeAlways present
duration_msintegerno
phone_numberentity refno
transcribedbooleanno

voicemail.transcribed​

subject is a voicemail reference.

detail fieldTypeAlways present
outcomeVoicemailTranscriptionOutcomeyes
duration_msintegerno
phone_numberentity refno
recordingentity refno

voicemail.listened​

subject is a voicemail reference.

detail fieldTypeAlways present
waited_msintegerno

Journeys​

A Member's progress through a Journey. Four of the five name the member as their subject; only journey.activated names the Journey.

journey.enrolled​

subject is a member reference.

detail fieldTypeAlways present
journeyentity refyes
triggerJourneyEnrollmentTriggerno

journey.unenrolled​

subject is a member reference.

detail fieldTypeAlways present
journeyentity refyes
reasonJourneyExitReasonno

journey.completed​

subject is a member reference.

detail fieldTypeAlways present
journeyentity refyes
step_countintegerno
duration_msintegerno

journey.step_transitioned​

subject is a member reference.

detail fieldTypeAlways present
journeyentity refyes
stepentity refyes
transitionJourneyTransitionyes
from_statusJourneyStepStatusno
to_statusJourneyStepStatusyes

journey.activated​

subject is a journey reference.

detail fieldTypeAlways present
step_countintegerno

Automation​

The machine working on its own, with nobody on the other end: Routine runs and a Workflow being published.

routine.started​

subject is a routine reference.

detail fieldTypeAlways present
routineentity refyes
triggerRoutineTriggeryes

routine.completed​

subject is a routine reference.

detail fieldTypeAlways present
routineentity refyes
outcomeRoutineOutcomeyes
duration_msintegerno

routine.failed​

subject is a routine reference.

detail fieldTypeAlways present
routineentity refyes
failureRoutineFailureyes
duration_msintegerno

workflow.published​

subject is a workflow reference.

detail fieldTypeAlways present
revisionentity refno
revision_numberintegeryes
task_countintegerno

Operators​

Who is available and who is in which operator group.

presence.went_online​

subject is a member reference.

detail fieldTypeAlways present
devicePresenceDeviceno
operator_groupslist of entity refno
live_workspaceslist of entity refno

presence.went_offline​

subject is a member reference.

detail fieldTypeAlways present
devicePresenceDeviceno
online_duration_msintegeryes
reasonPresenceOfflineReasonyes

operator_group.member_added​

subject is a operator_group reference.

detail fieldTypeAlways present
groupentity refyes
memberentity refyes

operator_group.member_removed​

subject is a operator_group reference.

detail fieldTypeAlways present
groupentity refyes
memberentity refyes

operator.interaction_declined​

subject is a member reference.

detail fieldTypeAlways present
interaction_idstringyes

Administration​

The account around the work: phone numbers, domains, settings, subscriptions and purchases.

member_subscription.started​

subject is a member_subscription reference.

detail fieldTypeAlways present
plan_slugstringyes
intervalBillingIntervalyes

member_subscription.canceled​

subject is a member_subscription reference.

detail fieldTypeAlways present
plan_slugstringno
reasonSubscriptionCancelReasonyes

phone_number.provisioned​

subject is a phone_number reference.

detail fieldTypeAlways present
number_kindPhoneNumberKindno
countrystringno
capabilitieslist of PhoneCapabilityno

phone_number.archived​

subject is a phone_number reference.

detail fieldTypeAlways present
reasonPhoneNumberArchiveReasonyes

config.updated​

subject is a workspace_config reference.

detail fieldTypeAlways present
areaConfigAreayes
actionConfigActionyes
field_slugslist of stringno
timezone_beforestringno
timezone_afterstringno
journey_status_beforeJourneyLifecycleStatusno
journey_status_afterJourneyLifecycleStatusno
journey_version_numberintegerno

connection.authorization_lost​

subject is a connection reference.

detail fieldTypeAlways present
connection_typestringyes

connection.authorization_restored​

subject is a connection reference.

detail fieldTypeAlways present
connection_typestringyes

Closed vocabularies​

Every value below comes from a closed set that grows by review. Treat a value you do not recognise as "ignore, do not error" — a new member is an additive change and will not be announced as a breaking one.

ActivityCapability​

apps:read, assignments:read, chats:read, journeys:read, members:read, operator:read, org:read, phones:read, records:read, workflows:read, workspace:read

ActorKind​

account, agent, connection, member, org_account, system, unattributed

AssignmentConclusion​

success, failed, referred, caller_hangup, member_unsubscribe, admin_canceled, expired, system_error, busy, no_answer

AssignmentTrigger​

api, journey, manual, rule, schedule

BillingInterval​

month, quarter, year, once

CallCompletionDisposition​

completed, busy, no-answer, failed, canceled

CallDirection​

inbound, outbound

CallNotPlacedReason​

admission_timed_out, expired

ChatAttentionReason​

agent_handed_off, escalation_open, legacy_unattributed, posture_awaits_human, unanswered_inbound

ChatChannel​

email, internal, sms, voice, web, whatsapp

ChatLane​

agent_job, dm, manager, workspace

ConfigAction​

created, deleted, updated

ConfigArea​

business_hours, escalation_settings, inbox, journey, phone_number, workspace_settings

EscalationReason​

agent_requested, member_requested, policy, tool_approval

EscalationResolution​

answered, approved, declined, expired

ImportSource​

api, connector_sync, csv

JourneyEnrollmentTrigger​

api, import, manual, rule

JourneyExitReason​

completed, manual, member_removed, rule

JourneyLifecycleStatus​

draft, active, paused, archived

JourneyStepStatus​

pending, eligible, in_progress, awaiting_delivery, held, completed, skipped, failed, timed_out

JourneyTransition​

activated, advanced, failed, skipped

MemberOrigin​

api, connector, import, manual, signup, system, org_api_key

MemberRemovalReason​

admin, deleted, merged, retention

MessageSendFailureClass​

provider_rejected, carrier_undelivered, carrier_failed, transport_error

MissedCallReason​

after_hours, no_answer, no_operator_online, rejected, timeout

PhoneCapability​

fax, mms, sms, voice

PhoneNumberArchiveReason​

admin, ported_out, released

PhoneNumberKind​

local, mobile, short_code, toll-free

PresenceDevice​

browser, phone, sip, unknown

PresenceOfflineReason​

disconnect, manual, timeout

RecordSourceChannel​

web_form, voice, sms, api, manager, sync, system

RoutineFailure​

canceled, error, timeout

RoutineOutcome​

no_action, partial, succeeded

RoutineTrigger​

api, manual, rule, schedule

SubscriptionCancelReason​

admin, migration, payment_failure, replaced, requested

VoicemailTranscriptionOutcome​

completed, failed

Timezone transitions in config.updated​

timezone_before/timezone_after are recorded only for a timezone change. An absent side means no value was recorded, not necessarily that the timezone was unset. It has two causes: an unset end of a legitimate transition — clearing a timezone sends timezone_before alone, and setting one where none was configured sends timezone_after alone — or a stored value that could not be represented, such as one written before the field was validated. Both absent means the change was recorded without values, for either of those reasons or for a historical row. The field still changed; field_slugs carries timezone.