Creating Webhooks

RingCentral supports oubound webhooks as a method of receiving notifications about events of interest to an application.

Registering a URL to receive webhooks from RingCentral

To create a webhook, you will first need a server that listens on a specific URL for events. You will register this webhook URL with RingCentral when creating the subscription via the Subscription API.

When you create a webhook subscription, RingCentral will transmit a test request to the designated URL in an attempt to verify all of the following prior to creating the subscription and transmitting events.

1. The URL must accessible by RingCentral and not behind a firewall
2. The web server supports TLS 1.2 or higher (see note below about TLS support)
3. The web server must respond within 3000 milliseconds
4. The web server must respond with an HTTP status code of 200 OK
5. The web server must respond with a valid Validation-Token header

Validating webhook URLs upon subscription creation

To ensure that the endpoints RingCentral interfaces with via webhooks are designed for RingCentral, RingCentral transmits a validation token in an HTTP header whenever a new webhook subscription is created. It is the expectation of RingCentral that your webhook handler echo back this validation token in the response via its own HTTP response header.

Below is an example of how validation tokens should be echoed in a trivial PHP app.

<?php
// Get validation token
$v = isset($_SERVER['HTTP_VALIDATION_TOKEN']) ? $_SERVER['HTTP_VALIDATION_TOKEN'] : '';
// Return validation token as header
if (strlen($v) > 0) {
  header("Validation-Token: {$v}");
}
?>

require 'sinatra'

post '/webhook' do
  v = request.env['HTTP_VALIDATION_TOKEN']
  unless v.nil? || v.length == 0
    headers['Validation-Token'] = v
    return
  end
end

Subscribing to events via a webhook

Webhook subscriptions are created using our Subscription API. The specific events you wish to receive a webhook for is specified via the eventFilters parameter. Each event filter corresponded to a different event you wish to be notified of. Furthermore, some event filters can be further refined via an event filter parameter which can further constrain the set of events you subscribe to, e.g. "I only want to receive to events pertaining to this specific webinar" (as opposed to all webinars).

Our API Reference is the definitive source for all the required fields in creating a subscription. The following sample request should however help you better understand at a high-level how a webhook subscription is created.

{
  "eventFilters": [
    "/restapi/v1.0/account/~/extension/~/presence?detailedTelephonyState=true&sipData=true",
    "/restapi/v1.0/account/~/extension/~/message-store",
    "/restapi/v1.0/account/~/extension/~/presence/line",
    "/restapi/v1.0/account/~/extension"
  ],
  "deliveryMode": {
    "transportType": "WebHook",
    "address": "https://myapp.ngrok.io/hook?auth_token=MySecureToken"
  }
}

Renewing webhooks that are about to expire

RingCentral webhooks can be effectively configured to never expire if their expiration date is set far enough into the future. However, it can be beneficial in some circumstances to be more conservative and subscribing to events for a set period of time. If that is helpful to you, then you may also need to occassionally renew webhooks subscriptions.

To help keep webhooks active and alive and not be impacted by their expiration, applications can subscribe to special reminder events using a subscription event filter. By passing an expiresIn property to this filter, one can be notified of a subscription prior to it expiring.

The subscription event filter has the following format, and uses a threshold and interval parameter to govern when reminders are sent and how often:

/restapi/v1.0/subscription/~?threshold=XXX&interval=YYY

Updating an existing webhook

To update a webhook, make a PUT request to the webhook subscription endpoint with the required event filters specified in the request body. Each PUT call, either sent with the event filters or with an empty body, automatically renews the subscription, updating its expiration time.

The renew a webhook, you can also make a POST request to the subscription renew endpoint.

Retrieve a list of active webhook subscriptions

To see a list of all the webhook and event subscriptions that are currently active, make a GET request to the subscription endpoint. This will return a list of all subscriptions, including webhooks and Web Socket push notifications.

Troubleshooting