Webhooks
Organization webhooks (Webhooks V2) are Gravity Rail's outbound webhook system. Configure endpoints at Organization → Webhooks: each endpoint receives a chosen set of activity event types across every Workspace it covers, with signed deliveries, a durable retry queue and an inline test send.
- Webhooks V2: the event catalog, payload, signing, delivery and API reference.
- Self-serve integration kit: the screens, commands and APIs for schemas, deliveries, attribution and recordings.
- Migration: how an integration built on the retired Webhooks V1 maps onto organization webhooks.
Webhooks V1 has been retired
Webhooks V1 was the per-Workspace Send Webhook (webhook:send) Action. It
has been removed: existing Send Webhook Actions were deleted, the Workspace
Settings → Webhooks delivery log is gone, and the Event Rules API, the
gr CLI, the SDK and the Manager no longer offer it.
An older Workspace archive, template, Workflow or Journey that still contains a
Send Webhook Action imports without it. The import or install result reports
the skipped Action with a retired_action diagnostic that points to
Organization → Webhooks. Every other Action in the definition is imported as
usual.
To rebuild a V1 integration, create an organization webhook endpoint and use Webhooks v1 → v2 to map each old trigger to its event type.
Receiving webhooks from your systems
Organization webhooks are outbound: Gravity Rail calling you. Your systems call Gravity Rail through one of these inbound paths, in the order you should reach for them.
1. Write directly to the API. To create or update Members, records or Chats, call the REST API with an API key. This is the right answer for most integrations. See Importing Data.
2. Trigger a Routine with a signed webhook. When an inbound event should run automation rather than write a row, enable the webhook trigger on a Routine. That gives you a URL to hand to your system:
POST https://api.gravityrail.com/api/v2/w/{workspace_uuid}/routines/{routine_uuid}/webhook
- Authentication is an HMAC signature; there is no API key on this
endpoint. Set
webhookEnabled: trueon the Routine and the server generates a per-Routine secret, returned aswebhookSecretPlaintextexactly once in that response. Store it then; it is not retrievable afterwards. Rotate withrotateWebhookSecret: true. SettingwebhookEnabled: falsewipes the secret and existing senders stop working immediately. - Header:
X-Routine-Signature - Format:
t={unix_timestamp},v1={hex_digest}, the same construction as the outboundX-Webhook-Signature: HMAC-SHA256 over the ASCII string{timestamp}.followed by the raw body bytes. You can reuse the code from Request signing, swapping the header name and the secret. - Replay window: signatures older than 5 minutes are rejected, as are future-dated ones beyond 30 seconds of clock skew. Sign at send time, not at build time.
- Body: any JSON, capped at 1 MB. The body is what you sign.
- Success:
200with{"run_uuid": "…", "status": "…"}. Keeprun_uuid: it identifies the Routine run your delivery started. - Errors:
401for a missing, malformed, expired or incorrect signature;404if the Routine does not exist or its webhook trigger is not enabled (the two are deliberately indistinguishable);413over 1 MB. The endpoint is rate-limited per Routine and per source IP. - Retries are idempotent-safe. The dedup key is derived from your signature, so re-sending the same signed delivery reuses the same Routine run instead of starting a second one. Retry by replaying the identical body and the identical signature header; re-signing the same body with a new timestamp produces a new run.
3. Provider and app-connection ingress. Inbound SMS, voice and fax arrive
on provider-specific endpoints that Gravity Rail configures for you when you
provision a phone number. They authenticate with the provider's own signature
scheme and are not open for you to call. Connected apps deliver their events to
connection-specific URLs managed from that connection's settings. There is
nothing to configure by hand for either. To react to those arrivals,
subscribe an organization webhook endpoint to the matching events, such as
chat.started, member.message_received, call.completed or
voicemail.transcribed.