Tyler Long
Jun 25 · 7 min read

What is a RingCentral WebHook?

First things first, a RingCentral WebHook is a mechanism for you to receive notifications from RingCentral. There are many kinds of event-triggered notifications, such as a new SMS, fax, incoming call, etc. Here is a complete list of notification types that RingCentral supports — you can setup a WebHook to receive the notifications for any of those on the list.

A WebHook in web development is a method of augmenting or altering the behavior of a web page, or web application, with custom callbacks. — Wikipedia

What are the requirements of a RingCentral WebHook URL?

Not all public URLs can be used as a WebHook URL. A valid WebHook URI should meet the following criteria:

  1. is available on the Internet because the URL needs to be public and accessible.
  2. Uses TLS 1.1 or greater / has SSL enabled (ie: https://, only need this in production). For Development TLS is not necessary.
  3. responds within 3000 milliseconds
  4. responds with Validation-Token header on subscription request (mentioned later in article)
  5. should NOT respond with a body larger than 1024 bytes — if the body is too large you will get {“errorCode”:”SUB-525",”message”:”WebHook server response is invalid”} when setting up the WebHook

After you’ve met these requirements, we’ll need to setup the actual WebHook subscription with an event filter.

What are event filters?

An event filter is the list of event types you’d like sent to your WebHook. For example, your event filter can include whenever an SMS is sent, when only new SMS messages are received, when someone answers a call, you have a missed call, or all of the above.

The event filters are comprised of an array of event types, which represented by the API resource you would need to call to access the object.

For example, below is a sample event filter array to have a WebHook triggered whenever you receive a new SMS or have an incoming phone call:

[“restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS”,“/restapi/v1.0/account/~/extension/~/presence?detailedTelephonyState=true”]

Once we know the event filters we want to subscribe to, the next step is to setup your WebHook script with a validation token so that it can be tested by our server.

What is a validation token?

The Validation token is a unique token auto specified by the RingCentral server. When the RingCentral server sends data to your WebHook URL, it will include a validation token in request HTTP header.

Your WebHook URL should include the SAME validation token value in the HTTP response header (Your WebHook URI should have the SAME validation token as the HTTP response headers).

For example, in PHP you would want to add the following code to your script’s header to return back to validation token:

<?php
// Get validation token
$v = isset($_SERVER[‘HTTP_VALIDATION_TOKEN’]) ? $_SERVER[‘HTTP_VALIDATION_TOKEN’] : ‘’;
// Return validation token as headerif (strlen($v) > 0) {header(“Validation-Token: {$v}”);}

Just remember, if the HTTP request from RingCentral to your WebHook URI contains the HTTP header Validation-Token, you also need to have this header with the same value in your HTTP response headers.

What’s the point of a validation token?

The validation token serves as an extra security measure, ensuring the WebHook URL being called is specifically designed for RingCentral and the data you send to it. This is designed to prevent accidental or third-party (in the case of a hijacked script where they do not echo back the validation token) actions from being taken against your production communication system.

Next you can optionally add a verification token.

What is a verification token?

Verification token is different from the validation token in that you optionally specify the value of the token yourself to ensure the request is coming from the RingCentral server (ie to prevent man in the middle attacks). If you do specify it, it will be included in the headers of the notification HTTP request.

Take the following C# code for example:

var subscriptionInfo = await rc.Restapi().Subscription().Post(new CreateSubscriptionRequest{eventFilters = new[] {“/restapi/v1.0/account/~/extension/~/presence?detailedTelephonyState=true”},deliveryMode = new NotificationDeliveryModeRequesttransportType = “WebHook”,address = “https://75ef5993.ngrok.io/webhook",verificationToken = “hello-world”});

When we setup the WebHook, we include deliveryMode.verificationToken in the request body. And whenever our WebHook gets a notification, there will be a Verification-Token in the headers:

Since HTTP header names are case-insensitive, you might get verification-token instead, just keep that in mind.

What’s the point of a verification token?

It lets you verify the value to confirm that it is the value that you specified. This lets you confirm that the notification is from RingCentral and not a malicious attack. Even if your WebHook URL is disclosed, your application is still relatively safe as long as you keep your verification token secret. If hackers don’t have the verification token they can’t send you fake RingCentral notifications.

After all that work you’ve done you want to make sure that you keep your WebHook alive.

How to keep a WebHook subscription alive?

WebHook subscriptions expire, but you can specify when. By using the expiresIn parameter you can set the WebHook’s lifetime in seconds, from 1 second (not sure I would suggest this) to up to 630,720,000 seconds (or 20 years!).

Note: when using a different transport type such as PubNub, the max expiresIn lifetime is 604,800 seconds (or 7 days).

Alternatively, you can set the expiresIn to a small value and refresh it yourself. Doing so will allow you to have better control over a WebHook’s life cycle. Here is how can you refresh a subscription in C#:

using (var rc = new RestClient(“clientID”, “clientSecret”, “serverURL”)){await rc.Authorize(“username”, “extension”, “password”);var result = await rc.Restapi(apiVersion).Subscription(subscriptionId).Put(modifySubscriptionRequest, updateSubscriptionParameters);}

And here is how you can refresh a subscription in JavaScript:

const SDK = require(‘ringcentral’);const rcsdk = new SDK({server: ‘serverURL’, appKey: ‘clientId’, appSecret: ‘clientSecret’});const platform = rcsdk.platform();await platform.login({ username: ‘username’, extension: ‘extension’, password: ‘password’ });const r = await platform.put(`/restapi/v1.0/subscription/${subscriptionId}`, modifySubscriptionRequest, updateSubscriptionParameters);

With that your WebHook is all set. However, if your WebHook stops working after you’ve created the subscription, it’s possible that something broke and your URL has become blacklisted.

Why is my WebHook blacklisted?

If your WebHook URL returns an unexpected HTTP status code (400, 500, etc.) it will be blacklisted by RingCentral after a short while. If it fails any of the reasons we mentioned above (i.e. fails to respond within 3000ms).

You can list subscriptions and check the blacklistedData property to know details about the blacklisted issue:

“blacklistedData”: {“reason”: “Webhook responses with code: [404], reason: [Not Found]”,“blacklistedAt”: “2018–08–03T12:44:03.105Z”}

If the WebHook URI fails to meet any of those requirements within 10 minutes, it will be blacklisted. After that, every 15 minutes, there will be a reconciliation and if your WebHook URI meets all the requirements again, the subscription will become active again.

If you don’t want to wait for the every 15 minutes reconciliation, you can just create a new subscription and remove the blacklisted one. John Wang built a project named rchooks that lets you create a new subscription and remove the blacklisted one.

If you checked if your WebHook was blacklisted and it’s still not working you will want to continue troubleshooting your WebHook.

How to troubleshoot WebHook issues?

Troubleshooting can be hard — depending on the issues you’re experiencing. Earlier I listed some of the common issues and recommendations on how to approach fixing them. It’s not a comprehensive list, but you could use it as a reference guide for when you’re struggling with figuring out what’s wrong.

  1. If your WebHook setup failed, check the response from the RingCentral server. Most of the time, there will be an error message that tells you what is wrong. For example: no validation token, unsuccessful HTTP response code from WebHook Uri, etc.
  2. If your WebHook URI stops receiving notifications.
    The first thing to troubleshoot is to list your subscriptions by making a HTTP GET /restapi/v1.0/subscriptions, check the response to see if the subscription is still active, and make sure that your subscription is not blacklisted. The second thing is to make sure your WebHook URI is still publicly accessible and can respond with successful HTTP status code in a timely manner. Also make sure your WebHook payload handling code is not throwing exception or filtering out useful data.

If you still cannot figure out what is wrong, you can contact RingCentral Dev Support by sending email to devsupport@ringcentral.com. You can expect to get a response in a business day.

WebHook or PubNub?

WebHook isn’t the only way to get notifications, but RingCentral also supports PubNub. WebHook and PubNub can be substituted for each other.

A couple reasons you might choose to use PubNub over a WebHook include the need for commercial support (as PubNub is a commercial product) or security or firewalls that prevent your URL from being publicly available.

We recommend you use WebHook instead of PubNub whenever you can. Because WebHook is based on open standards and we have full control over it. That being said, PubNub is still a great option, use it if you can’t get a public URL for your app.

Now that you have a better understanding of RingCentral WebHooks, it’s time to build your own!

Getting started

You can get started with WebHooks using any of our getting started guides for JavaScript, Python, PHP, or C#. You can also find more tutorials and resources on our developer site.

For more information on what the RingCentral WebHook is read John Wang’s article RingCentral WebHooks Introduction.

Hooked on RingCentral? Be sure to join us at CoderCruise — our developer conference on a cruise ship — to learn even more about RingCentral’s APIs, WebHooks, and the future of technology!

RingCentral Developers

Cloud Business Communications

Thanks to Phong Vu

Tyler Long

Written by

RingCentral Developers

Cloud Business Communications

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade