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
| Scope | All of the organization's workspaces, selected workspaces (named, labelled, or both), or none |
| Vocabulary | A closed set of activity event types — see the catalog |
| Payload | One shape for every event type. Identifiers only |
| Delivery | A durable queue: at-least-once, retried for up to a day, held for 7 days |
| Signing | HMAC-SHA256 over the raw body — see Request signing |
| Testing | A Send test event button on every endpoint, with an editable payload |
Setting one up
- 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. - 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
workspaceScopeobject — see Notes on the shapes. - 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. - 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 log | org:webhooks — org admins hold it automatically |
| Create, update, delete, send a test | Org admin, subject to the organization's interactive MFA policy |
| See which org endpoints your workspace feeds | webhooks: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"
}
}
| Field | What it is |
|---|---|
id | This occurrence's own uuid |
occurred_at | When it happened, UTC, timezone-aware |
event_type | One of the catalog values |
event_version | Envelope version. Bumped only if the envelope's own shape changes |
visibility | Always workspace on a delivered event |
workspace_uuid | The workspace the event rolled up under |
org_uuid | Always the delivering endpoint's organization, whatever the underlying event recorded |
account_uuid | The account, when the occurrence names one |
actor | Who caused it: {kind, uuid}, uuid null exactly when kind is system or unattributed. See Actors |
subject | The entity the event is about, as a typed reference |
refs | Other entities the occurrence names, same shape as subject |
detail | The typed payload — varies by event type, see the catalog |
dedupe_key | Names 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_discriminator | An input to dedupe_key, not information. Ignore it |
endpoint | Which 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:
| Kind | Meaning |
|---|---|
member | A person in the workspace, including a member acting on their own record |
agent | An Agent. Recorded as agent even when it acts through a member session; uuid is the Agent's member id |
account | An account acting without a workspace membership, such as an administrator |
org_account | An organization-scoped account. Reserved: not emitted today |
connection | An 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) |
system | No person or Agent was involved: a schedule, or an inbound carrier or billing event |
unattributed | Someone 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.sentwhen its recipient is a Member. Itsdetailthen carries nochatand nomessage_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.failedin 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_enteredandmember.message_receivedare not recorded for a test-run Assignment or Chat. - Message text.
member.message_receivednames 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 got | Read it with | Scope |
|---|---|---|
A member ref | GET /api/v2/w/{workspace_uuid}/members/by-uuid/{uuid} | members:read |
A data_record ref | GET /api/v2/w/{workspace_uuid}/data-types/records/by-uuid/{uuid} | records:read |
call.completed / call.summary subject, or a data_record.* detail.call | GET /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 404 | chats:read |
detail.recording on call.completed or voicemail.transcribed | An 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 route | chats: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 / summaryUpdatedAt | chats: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 subject | GET /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 here | members:read |
detail.workflow, detail.task, detail.task_lineage_uuid | Configuration identifiers to match against. Take them from the Workflow in the app; task_lineage_uuid is the one that survives a publish | — |
Delivery
| Method | POST |
Content-Type | application/json |
| Body | JSON with alphabetically sorted keys, UTF-8 |
| Signature header | X-Webhook-Signature — HMAC-SHA256, see Request signing |
| Timeout | 30 seconds total, connection included |
| Redirects | Not followed |
| Success | Any 2xx |
| Retries | Up 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}. Thev1label 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.
| Value | The write |
|---|---|
web_form | A signup, or a public Site form (CCM enrollment). A records API call outside a Site session is api |
voice | An Agent wrote the record during a voice chat |
sms | An Agent wrote the record during SMS |
api | The records API, an import, or a member upsert |
manager | An Agent or the app, and not a phone call or SMS |
sync | A connector sync |
system | A 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, plusdata_record.createdif 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, plusmembers:readif you also need the owning Member. Send it asAuthorization: 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
}
| Status | Meaning |
|---|---|
200 | The record. fieldValues is keyed by field slug |
403 | The key lacks records:read |
404 | Not 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 type | Stored and returned as | Example |
|---|---|---|
date | An ISO 8601 calendar date. No time, no timezone | "2026-09-23" |
datetime | ISO 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.
| Moment | What you receive |
|---|---|
| First Site submit that creates the record | One 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 fields | One data_record.updated for the slugs that changed, source_channel web_form |
| A Site submit whose values already match the record | No record event |
A practice rule that then stamps enrollment_date and consent_timestamp | A 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 queue | call.queued on the Chat. Queued is not ringing |
| A queued call is not placed | call.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 starts | call.started when the call row is created |
| A connected call ends | call.completed |
| A call never connects | call.missed |
| An Agent writes the record during a phone call | data_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 SMS | source_channel sms, detail.chat naming the SMS chat, no call |
| Pathways confirms a first appointment the Agent booked | data_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.
| Slug | Label | Type | Example | Meaning |
|---|---|---|---|---|
enrollment_channel | Enrollment Channel | enum: voice_conversation, web_form, care_team | web_form | Channel the patient enrolled through. The Site writes web_form |
visit_medium | Visit Medium | enum: sms, email | sms | How they opened the enrollment link. Absent when the link had no medium |
call_status | Call Status | enum: reached, not_available, callback_requested, left_message | callback_requested | Whether they were reached. Callback requested is this value, not its own field |
callback_date | Callback Date | datetime | 2026-10-14T15:00:00-04:00 | Time they asked to be called. Not a confirmed booking. Keep the offset |
first_appointment | First Appointment | datetime | 2026-10-16T14:30:00-04:00 | First 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_notes | Call Notes | long text | Prefers a call after lunch. | Notes from the enrollment call. There is no field named notes |
enrollment_status | Enrollment Status | enum: enrolled, follow_up, declined, pending, digital_outreach_completed | enrolled | Decision recorded on the form. digital_outreach_completed means the text and email outreach sequence ended with no decision from the patient |
enrollment_date | Enrollment Date | datetime | 2026-10-14T18:02:11.483920+00:00 | Instant 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_verified | Identity Verified | boolean | true | Name and date of birth were accepted for this session |
consent_given | Consent Given | boolean | true | Consent to enroll |
consent_timestamp | Consent Timestamp | datetime | 2026-10-14T18:02:11.484102+00:00 | Instant 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_in | Text Reminders Opted In | boolean | true | Opt-in for care-coordinator text reminders |
sms_phone_number | SMS Phone Number | phone | +15555550199 | Set only when text reminders are on. Cleared when they opt out |
contact_phone | Contact phone | text | +15555550199 | Number they typed. Not verified |
contact_email | Contact email | text | ada@example.com | Address they typed. Not verified |
email_consent | Email consent | boolean | false | Agreed to email contact |
decline_reason | Decline Reason | long text | Not at this time. | Why they declined |
cost_disclosure_type | Cost Disclosure Type | enum: out-of-pocket, co-insurance, none | none | Which cost disclosure was given |
visit_source | Visit Source | text | spring-mailer | Campaign or referral on the link |
authority_to_consent | Authority to Consent | enum: patient_self, caregiver_spouse, caregiver_non_spouse | patient_self | Whose authority the consent rests on |
consenting_party | Consenting Party | text | Ada Lovelace | Name of the person who gave consent: the patient, or the caregiver consenting for them |
poa_verbally_confirmed | POA Verbally Confirmed | enum: yes, no | yes | Caregiver 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
| Route | What it does |
|---|---|
GET/POST /api/v2/o/{org_uuid}/webhooks | List 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-types | The closed subscribable vocabulary |
GET /api/v2/o/{org_uuid}/webhooks/event-types/{event_type}/sample | A representative payload for one type |
POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/test | Send one payload now; returns the outcome |
GET /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/deliveries | Delivery 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}/replay | Re-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-pending | Move 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/clear | Body {"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}/coverage | Which covered workspaces have a Form opted in to record events |
GET /api/v2/w/{workspace_uuid}/webhook-logs/org-endpoints | From inside a workspace: which org endpoints it feeds |
GET/POST /api/v2/o/{org_uuid}/workspace-labels | List 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}/labels | Read or replace one workspace's labels (unknown slugs create labels) |
POST /api/v2/o/{org_uuid}/workspace-labels/preview-scope | Which 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": [...]}.selectedneeds at least one workspace or label;allandnonetake neither list. Both mistakes are a422: the mode is never inferred from empty lists. SendlabelSelectoras label slugs; each must be an existing label of your organization, and each workspace must be one of its workspaces (otherwise400).workspaceUuidstakes at most 100 entries andlabelSelectorat most 10; a longer list is a422. -
Create requires
workspaceScope. On update, omittingworkspaceScopeleaves coverage unchanged; sending it replaces the whole selection — mode, workspaces and labels — so{"mode": "none"}stops all delivery. The former top-levelworkspaceUuids,labelSelectorandlimitedToWorkspacesfields are refused with422. -
Endpoint reads return
workspaceScopewithmode,workspaceUuids(sorted) andlabelSelectoras label summaries (uuid,slug,name,color).modeis read from what is stored: aselectedendpoint whose last workspace was deleted and that has no labels readsnoneand 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-scopetakes the sameworkspaceScopeobject as its body (for example{"mode": "selected", "labelSelector": ["production"]}) and returnsworkspaceCount— how many workspaces it reaches right now — and the first few by name.nonereaches 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;statusHistoryrecords why it stopped. -
Each endpoint carries
deliveryHealth:state:healthy,failing(attempts are failing, events still flow) orheld(Gravity Rail holds the queue and retries one delivery atnextProbeAt). An endpoint with no recorded attempt ishealthywithlastSuccessAt: null.consecutiveFailures: failed attempts in a row, across deliveries.failingSince: the first failure of the current run;nullwhile healthy.lastSuccessAt,lastFailureAt,lastFailureClass(network,http_4xx,http_5xx,unsafe_target,missing_secretorretryable).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://hostplus 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, orselectedwhen 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 holdingwebhooks: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 field | Type | Always present |
|---|---|---|
origin | MemberOrigin | no |
connection | entity ref | no |
account | entity ref | no |
capabilities | list of ActivityCapability | no |
requested_by | entity ref | no |
member.removed
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
reason | MemberRemovalReason | yes |
account | entity ref | no |
member.role_changed
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
account | entity ref | no |
capabilities | list of ActivityCapability | no |
member.labels_changed
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
added | list of entity ref | no |
removed | list of entity ref | no |
member.attributes_changed
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
field_slugs | list of string | no |
data_type | entity ref | no |
import.started
subject is a import reference.
detail field | Type | Always present |
|---|---|---|
source | ImportSource | yes |
connection | entity ref | no |
expected_rows | integer | no |
import.completed
subject is a import reference.
detail field | Type | Always present |
|---|---|---|
source | ImportSource | yes |
connection | entity ref | no |
created_count | integer | no |
updated_count | integer | no |
skipped_count | integer | no |
failed_count | integer | no |
duration_ms | integer | no |
data_record.created
subject is a data_record reference.
detail field | Type | Always present |
|---|---|---|
is_test | boolean | no |
field_slugs | list of string | no |
data_type | entity ref | no |
source_channel | RecordSourceChannel | no |
chat | entity ref | no |
call | entity ref | no |
data_record.updated
subject is a data_record reference.
detail field | Type | Always present |
|---|---|---|
is_test | boolean | no |
field_slugs | list of string | no |
data_type | entity ref | no |
source_channel | RecordSourceChannel | no |
chat | entity ref | no |
call | entity ref | no |
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 field | Type | Always present |
|---|---|---|
workflow | entity ref | no |
revision_number | integer | no |
trigger | AssignmentTrigger | no |
assignment.concluded
subject is a assignment reference.
detail field | Type | Always present |
|---|---|---|
workflow | entity ref | no |
outcome | AssignmentConclusion | yes |
task_count | integer | no |
completed_task_count | integer | no |
duration_ms | integer | no |
assignment.task_entered
subject is a assignment reference.
detail field | Type | Always present |
|---|---|---|
task | entity ref | yes |
task_lineage_uuid | uuid | no |
workflow | entity ref | no |
revision_number | integer | no |
member | entity ref | no |
chat | entity ref | no |
chat.started
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
lane | ChatLane | yes |
channel | ChatChannel | yes |
initiated_by | ActorKind | yes |
requested_by | entity ref | no |
assistant | entity ref | no |
chat.awaiting_human
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
reasons | list of ChatAttentionReason | yes |
cleared_reasons | list of ChatAttentionReason | no |
is_test | boolean | no |
chat.human_replied
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
cleared_reasons | list of ChatAttentionReason | no |
waited_ms | integer | no |
reply_message_uuid | uuid | no |
reply_member | entity ref | no |
chat.call_ended
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
reasons | list of ChatAttentionReason | no |
cleared_reasons | list of ChatAttentionReason | no |
chat.auto_replied
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
reasons | list of ChatAttentionReason | no |
cleared_reasons | list of ChatAttentionReason | no |
chat.summary
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
channel | ChatChannel | yes |
message.sent
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
channel | ChatChannel | yes |
chat | entity ref | no |
message_uuid | uuid | no |
message.send_failed
subject is a workspace reference.
detail field | Type | Always present |
|---|---|---|
channel | ChatChannel | yes |
failure_class | MessageSendFailureClass | yes |
count | integer | no |
member.message_received
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
channel | ChatChannel | yes |
chat | entity ref | no |
message_uuid | uuid | no |
assignment | entity ref | no |
workflow | entity ref | no |
task | entity ref | no |
escalation.opened
subject is a escalation reference.
detail field | Type | Always present |
|---|---|---|
reason | EscalationReason | yes |
chat | entity ref | no |
is_test | boolean | no |
escalation.resolved
subject is a escalation reference.
detail field | Type | Always present |
|---|---|---|
resolution | EscalationResolution | yes |
open_ms | integer | no |
chat | entity ref | no |
call.started
subject is a call reference.
detail field | Type | Always present |
|---|---|---|
direction | CallDirection | yes |
phone_number | entity ref | no |
outbound_call_intent | uuid | no |
requested_by | entity ref | no |
assistant | entity ref | no |
call.completed
subject is a call reference.
detail field | Type | Always present |
|---|---|---|
direction | CallDirection | yes |
outcome | CallCompletionDisposition | yes |
duration_ms | integer | no |
phone_number | entity ref | no |
recording | entity ref | no |
call.missed
subject is a call reference.
detail field | Type | Always present |
|---|---|---|
direction | CallDirection | yes |
reason | MissedCallReason | yes |
phone_number | entity ref | no |
call.summary
subject is a call reference.
detail field | Type | Always present |
|---|---|---|
channel | ChatChannel | yes |
chat | entity ref | no |
call.queued
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
outbound_call_intent | uuid | yes |
requested_by | entity ref | no |
call.not_placed
subject is a chat reference.
detail field | Type | Always present |
|---|---|---|
outbound_call_intent | uuid | yes |
reason | CallNotPlacedReason | yes |
voicemail.received
subject is a voicemail reference.
detail field | Type | Always present |
|---|---|---|
duration_ms | integer | no |
phone_number | entity ref | no |
transcribed | boolean | no |
voicemail.transcribed
subject is a voicemail reference.
detail field | Type | Always present |
|---|---|---|
outcome | VoicemailTranscriptionOutcome | yes |
duration_ms | integer | no |
phone_number | entity ref | no |
recording | entity ref | no |
voicemail.listened
subject is a voicemail reference.
detail field | Type | Always present |
|---|---|---|
waited_ms | integer | no |
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 field | Type | Always present |
|---|---|---|
journey | entity ref | yes |
trigger | JourneyEnrollmentTrigger | no |
journey.unenrolled
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
journey | entity ref | yes |
reason | JourneyExitReason | no |
journey.completed
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
journey | entity ref | yes |
step_count | integer | no |
duration_ms | integer | no |
journey.step_transitioned
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
journey | entity ref | yes |
step | entity ref | yes |
transition | JourneyTransition | yes |
from_status | JourneyStepStatus | no |
to_status | JourneyStepStatus | yes |
journey.activated
subject is a journey reference.
detail field | Type | Always present |
|---|---|---|
step_count | integer | no |
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 field | Type | Always present |
|---|---|---|
routine | entity ref | yes |
trigger | RoutineTrigger | yes |
routine.completed
subject is a routine reference.
detail field | Type | Always present |
|---|---|---|
routine | entity ref | yes |
outcome | RoutineOutcome | yes |
duration_ms | integer | no |
routine.failed
subject is a routine reference.
detail field | Type | Always present |
|---|---|---|
routine | entity ref | yes |
failure | RoutineFailure | yes |
duration_ms | integer | no |
workflow.published
subject is a workflow reference.
detail field | Type | Always present |
|---|---|---|
revision | entity ref | no |
revision_number | integer | yes |
task_count | integer | no |
Operators
Who is available and who is in which operator group.
presence.went_online
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
device | PresenceDevice | no |
operator_groups | list of entity ref | no |
live_workspaces | list of entity ref | no |
presence.went_offline
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
device | PresenceDevice | no |
online_duration_ms | integer | yes |
reason | PresenceOfflineReason | yes |
operator_group.member_added
subject is a operator_group reference.
detail field | Type | Always present |
|---|---|---|
group | entity ref | yes |
member | entity ref | yes |
operator_group.member_removed
subject is a operator_group reference.
detail field | Type | Always present |
|---|---|---|
group | entity ref | yes |
member | entity ref | yes |
operator.interaction_declined
subject is a member reference.
detail field | Type | Always present |
|---|---|---|
interaction_id | string | yes |
Administration
The account around the work: phone numbers, domains, settings, subscriptions and purchases.
member_subscription.started
subject is a member_subscription reference.
detail field | Type | Always present |
|---|---|---|
plan_slug | string | yes |
interval | BillingInterval | yes |
member_subscription.canceled
subject is a member_subscription reference.
detail field | Type | Always present |
|---|---|---|
plan_slug | string | no |
reason | SubscriptionCancelReason | yes |
phone_number.provisioned
subject is a phone_number reference.
detail field | Type | Always present |
|---|---|---|
number_kind | PhoneNumberKind | no |
country | string | no |
capabilities | list of PhoneCapability | no |
phone_number.archived
subject is a phone_number reference.
detail field | Type | Always present |
|---|---|---|
reason | PhoneNumberArchiveReason | yes |
config.updated
subject is a workspace_config reference.
detail field | Type | Always present |
|---|---|---|
area | ConfigArea | yes |
action | ConfigAction | yes |
field_slugs | list of string | no |
timezone_before | string | no |
timezone_after | string | no |
journey_status_before | JourneyLifecycleStatus | no |
journey_status_after | JourneyLifecycleStatus | no |
journey_version_number | integer | no |
connection.authorization_lost
subject is a connection reference.
detail field | Type | Always present |
|---|---|---|
connection_type | string | yes |
connection.authorization_restored
subject is a connection reference.
detail field | Type | Always present |
|---|---|---|
connection_type | string | yes |
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.
Related
- Webhooks v1 → v2 — moving an integration from the retired Send Webhook Action
- Request signing — the HMAC scheme and verification code
- Self-serve integration kit — where to view schemas, deliveries, and recordings