Self-serve integration kit
This page points at the screen, command, or API for each integration step. Payload, delivery, and enrollment contracts stay on Webhooks v2.
Commands below use yarn gr. The published CLI is the same gr binary. Set WORKSPACE_UUID to the workspace and ORG_UUID to the organization. Writes need --allow-write.
Forms, schemas, and field slugs
Open Knowledge → Data, then the Form. Each field row shows its identifier. Hover the row to copy it. The Forms guide covers the editor.
Record events are off until the Form publishes them. On the Form, open Settings and turn on Publish this form's entry events under Organization webhooks.
yarn gr data-types list -w $WORKSPACE_UUID
yarn gr data-types get -w $WORKSPACE_UUID --id $DATA_TYPE_ID
yarn gr data-types get-by-slug -w $WORKSPACE_UUID --slug $FORM_SLUG
yarn gr data-types update -w $WORKSPACE_UUID --id $DATA_TYPE_ID \
--data '{"webhookEventsEnabled":true}' --allow-write
fields on the get response is the schema. Each entry's slug is the identifier later deliveries use.
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/data-types/$DATA_TYPE_ID"
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/data-types/slug/$FORM_SLUG"
Every schema change appends an immutable version. Read the history with:
yarn gr data-types schema versions -w $WORKSPACE_UUID --id $DATA_TYPE_ID
Change the schema with the fields editor in the UI, or with PUT /api/v2/w/$WORKSPACE_UUID/data-types/$DATA_TYPE_ID in the API.
Rename a field slug
Use Rename identifier... on the saved field (⋯ beside Identifier). An ordinary save does not rename it. Preview first. The preview lists Gravity Rail references that still name the old slug. It does not list a mapping in your receiver.
yarn gr data-types fields rename-preview -w $WORKSPACE_UUID \
--data-type-id $DATA_TYPE_ID --slug $OLD_SLUG --new-slug $NEW_SLUG
yarn gr data-types fields rename -w $WORKSPACE_UUID \
--data-type-id $DATA_TYPE_ID --slug $OLD_SLUG --new-slug $NEW_SLUG --allow-write
curl -X POST -H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"newSlug":"'"$NEW_SLUG"'"}' \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/data-types/$DATA_TYPE_ID/fields/$OLD_SLUG/rename-preview"
Apply is the same path with /rename instead of /rename-preview.
What that does to field_slugs is in Check that the delivery names your field. Short version: past deliveries keep the old slug, the value move itself sends no record event, and the next write lists the new slug. Change your mapping yourself.
Which slug a field has
| Surface | Where |
|---|---|
| App | Knowledge → Data → the field row's identifier. Forms |
| CLI | yarn gr data-types get -w $WORKSPACE_UUID --id $DATA_TYPE_ID or get-by-slug --slug $FORM_SLUG |
| API | GET /api/v2/w/{workspace_uuid}/data-types/{data_type_id} or .../data-types/slug/{slug} |
On a delivery, the slugs that write touched are detail.field_slugs. That list is not the whole schema.
When a webhook fired, and how to replay
Open Organization → Webhooks. The organization webhooks guide covers create, test, and each endpoint’s Deliveries and Settings tabs. Each delivery row shows the event type, queue status, attempt count, and latest response. Filter by status and event date range, and page through the matching deliveries. Dates use the browser timezone. Admins can choose Retry delivery on an eligible row or expand it to inspect requests and responses.
yarn gr org webhooks list --org $ORG_UUID
yarn gr org webhooks get --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID
yarn gr org webhooks deliveries --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/o/$ORG_UUID/webhooks/$ENDPOINT_UUID/deliveries"
The delivery log does not include the body that was sent. The shape for an event type is:
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/o/$ORG_UUID/webhooks/event-types/data_record.updated/sample"
The catalog is Webhooks v2. Enrollment timing and example bodies are CCM enrollment.
Replay keeps the same dedupe_key and occurred_at. The endpoint must be active; a paused or disabled endpoint answers 409.
curl -X POST -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/o/$ORG_UUID/webhooks/$ENDPOINT_UUID/deliveries/$DELIVERY_ID/replay"
Gap. There is no gr org webhooks replay. Use Retry delivery on the expanded delivery, or the POST above.
Disabled and resumed
Failed deliveries never automatically disable an endpoint. After 5 failed attempts in a row, Gravity Rail holds the endpoint's queue: waiting events spend no attempts, one delivery is retried at a doubling interval up to hourly, and the first success sends the rest. Gravity Rail attempts to warn admins when it holds the endpoint or a delivery dead-letters; notices are best-effort. Confirmed notices suppress reminders for one day. If no warning is confirmed, later failures may retry notification after 15 minutes, which can produce duplicate mail. Each delivery gets up to 12 attempts; other events continue after it dead-letters. Operator pauses hold pending events for up to 7 days. The rules are When your receiver stays broken.
Pause or Resume is on the endpoint card. statusHistory records operator changes and historical automatic disables. Failure warnings arrive while the endpoint stays active.
yarn gr org webhooks pause --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID --allow-write
yarn gr org webhooks resume --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID --allow-write
PATCH /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid} with "status": "active" is the same resume. Replay still requires active.
If your receiver will reject the held events, discard them before you resume. Clear all deliveries is in the delivery history menu on the endpoint’s Deliveries tab. It also clears visible history. The CLI still offers a queue-only operation for paused or disabled endpoints:
yarn gr org webhooks discard-pending --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID --allow-write
Which Forms are publishing record events:
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/o/$ORG_UUID/webhooks/$ENDPOINT_UUID/coverage"
The endpoint’s Settings tab loads the same Form coverage automatically.
Web form, call, or SMS
Use detail.source_channel on data_record.created and data_record.updated. The table is Reading a field value. web_form is a signup or a public Site form. voice and sms are Agent writes on those channels. A phone call itself is call.queued, call.started, call.completed, call.missed, call.not_placed, or call.summary, not a record event. call.queued and call.not_placed name the Chat: an automated call accepted into the paced call queue records call.queued, then call.started when its call row is created, or call.not_placed if it is not placed. A call.not_placed with detail.reason expired can follow a call.started for the same intent: the call row existed, but no call was made. That row also ends with call.missed (reason rejected); call.not_placed is the outcome to act on.
actor.kind is not the channel. A Site submit and a voice booking can both show actor.kind of member.
For the enrollment Form, field meaning and event timing are CCM enrollment. enrollment_channel is a field on the record. It is not source_channel.
Recordings and transcripts
Webhooks do not include audio, transcripts, or field values. detail.recording on call.completed and voicemail.transcribed is an id, and it is often null because the event can fire before a recording row exists.
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/calls/by-uuid/$CALL_UUID"
That response has chatId. It does not have the audio. The whole-call download URL uses that chat id, and the transcript is the chat:
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/recordings/chat/$CHAT_ID/download-url"
curl -H "Authorization: Bearer $GR_API_KEY" \
"https://api.gravityrail.com/api/v2/w/$WORKSPACE_UUID/chats/$CHAT_ID"
The details are Fetching call audio and transcript. The key needs chats:read.
Gap. There is no recordings-by-uuid route. A call with no chat answers 404 on calls/by-uuid and has no recording fetch.
SDK and API quickstart
| Start here | URL |
|---|---|
| TypeScript SDK | Libraries / SDK — npm install @gravity-rail/sdk |
| Authentication and keys | Authentication |
| REST reference | API reference |
| CLI | CLI |
| PHI boundary | Data use and PHI |
Organization webhook routes are the v2 API table.
Test and sandbox
Send test event on the endpoint posts one signed sample and returns your HTTP status. It queues nothing, writes no delivery row, and cannot disable the endpoint. Edit the JSON before sending. Details are Testing.
yarn gr org webhooks test-send --org $ORG_UUID --endpoint-uuid $ENDPOINT_UUID \
--event-type data_record.created --allow-write
The API is POST /api/v2/o/{org_uuid}/webhooks/{endpoint_uuid}/test.
Gap. There is no Gravity Rail sandbox workspace for an external integrator. Point an endpoint at a URL you control, including a paused or disabled endpoint, and use Send test event there. A test body has "test": true.