Webhooks

How the gateway receives inbound SMS from RingCentral and forwards them to your application.

You do not call this endpoint

POST /v1/webhooks/ringcentral is called by RingCentral, not by your application. This page documents the internal webhook receiver so you understand the inbound SMS pipeline. To receive inbound SMS in your app, configure a webhookUrl on your app or connect via WebSocket.

POST/v1/webhooks/ringcentralVerification-Token header

Receives inbound SMS events from RingCentral.

How it works

Handshake — When RingCentral creates a subscription, it sends a request with a Validation-Token header. The gateway echoes this header back in the response to confirm the endpoint.
Verification — Subsequent webhook events include a Verification-Token header. The gateway verifies it against the stored token before processing the event.
Processing — Valid inbound SMS events are parsed, deduplicated by rcMessageId, stored as a message record, and published to WebSocket subscribers.
Fan-out — The gateway sends the inbound SMS to all active apps in the tenant that have a webhookUrl configured.

Fan-out payload

When an inbound SMS arrives, the gateway sends the following JSON payload via HTTP POST to each app's webhookUrl:

Payload your app receives

{
  "type": "sms_inbound",
  "messageId": "msg_a1b2c3d4e5f6",
  "from": "+15551234567",
  "to": "+15559876543",
  "body": "Hey, is my appointment still on?",
  "rcMessageId": "12345678",
  "tenantId": "tenant_abc123def456abcd",
  "timestamp": "2026-03-01T14:30:00.000Z"
}

Payload fields

Field	Type	Description
`type`	`string`	Always `"sms_inbound"`.
`messageId`	`string`	Gateway message ID.
`from`	`string`	Sender phone number.
`to`	`string`	Recipient phone number (your RC number).
`body`	`string`	Message text content.
`rcMessageId`	`string \| null`	RingCentral message ID.
`tenantId`	`string`	Tenant that received the message.
`timestamp`	`string`	ISO 8601 timestamp.

Test webhook payload

When you call POST /v1/apps/:appId/test-webhook, the gateway sends a test payload instead:

Test payload

{
  "type": "test",
  "timestamp": "2026-03-01T12:00:00.000Z",
  "source": "smsgateway"
}

Related docs

Webhooks Guide — Setup, URL validation, and delivery details
Receiving SMS — Full inbound SMS walkthrough
WebSocket — Real-time alternative to webhooks