Sign in

v1

latestOpenAPI 3.0.3RingCentral API License Agreement2026-08-064871,2921.5 MB
Subscriptions

Create Subscription

This API allows client applications to register a new subscription so that it can be notified of events when they occur on the platform.

A subscription relates to a set of events that a client application would like to be informed of and the delivery channel by which they will be notified of those events. How subscriptions are established depends upon the notification channel the client application would like to use to receive the event notification. For example, to create a webhook a developer would create a subscription via a REST API call, while specifying a list of events or "event filters" to be notified of, a transport type of WebHook, and the address or URL to which they would like the webhook delivered.

However, developers wishing to subscribe to a set of events via a WebSocket channel, would first connect to the WebSocket gateway, and then issue their subscription request over the WebSocket itself, as opposed to making a REST API call to this endpoint.

While the protocol for establishing a subscription may vary depending upon the delivery channel for that subscription, the schemas used for representing a subscription are the same across all delivery modes.

Subscriptions are currently limited to 20 subscriptions per user/extension (for particular application).

RingCentral currently supports the following delivery modes for event subscriptions:

  • WebHook - to receive event notifications as an HTTP POST to a given URL
  • WebSocket - to receive real-time events over a persistent WebSocket connection
  • PubNub (deprecated) - to receive a push notification sent directly to a client application

Developers should be aware that the PubNub delivery mode is currently deprecated and will be removed in 2024. Developers are encouraged to migrate their client applications to use WebSockets instead.

post/restapi/v1.0/subscription

Request body

eventFiltersstring[] required

The list of event filters corresponding to events the user is subscribed to

expiresIninteger

Subscription lifetime in seconds. The maximum subscription lifetime depends upon the specified transportType:

Transport typeMaximum permitted lifetime
WebHook315360000 seconds (10 years)
RC/APNS, RC/GSM7776000 seconds (90 days)
PubNub900 seconds (15 minutes)
WebSocketn/a (the parameter is ignored)

Example request

{
  "expiresIn": 1200,
  "deliveryMode": {
    "address": "https://acme.com/myservice/webhook"
  }
}

Response

Successful response

uristring uri required

Canonical URI of a subscription resource

idstring required

Internal identifier of a subscription

eventFiltersstring[] required

The list of event filter names corresponding to events the user is subscribed to

expirationTimestring date-time required

Subscription expiration time in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z

expiresIninteger

Subscription lifetime in seconds

status'Active' | 'Blacklisted' required

Subscription status

creationTimestring date-time required

Subscription creation time in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534

Example response

{
  "id": "95fecfc9-9cdc-4e94-a78a-89fd65889d37",
  "deliveryMode": {
    "address": "https://acme.com/myservice/webhook"
  }
}