Skip to main content

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: true on the Routine and the server generates a per-Routine secret, returned as webhookSecretPlaintext exactly once in that response. Store it then; it is not retrievable afterwards. Rotate with rotateWebhookSecret: true. Setting webhookEnabled: false wipes the secret and existing senders stop working immediately.
  • Header: X-Routine-Signature
  • Format: t={unix_timestamp},v1={hex_digest}, the same construction as the outbound X-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: 200 with {"run_uuid": "…", "status": "…"}. Keep run_uuid: it identifies the Routine run your delivery started.
  • Errors: 401 for a missing, malformed, expired or incorrect signature; 404 if the Routine does not exist or its webhook trigger is not enabled (the two are deliberately indistinguishable); 413 over 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.