Common Questions on RingCentral WebHooks
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:
- is available on the Internet because the URL needs to be public and accessible.
- Uses TLS 1.1 or greater / has SSL enabled (ie: https://, only need this in production). For Development TLS is not necessary.
- responds with HTTP 200 status code within 3000 milliseconds
- responds with Validation-Token header on subscription request (mentioned later in article)
- should NOT respond with a response larger than 1024 bytes — if the response is too large you will get {“errorCode”:”SUB-525",”message”:”WebHook server response is invalid”} when setting up the WebHook. And the response size counts both the body and the headers.
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.
Why are some event filters disabled?
When you setup the WebHook, you may specify as many event filters as you can, but we don’t promise that all of them will be enabled. You need to check the response of the WebHook setup API request. If you see something like the following:
..."disabledFilters":[{"filter":"/restapi/v1.0/account/123456/telephony/sessions","reason":"SUB-410","message":"Required application permission [CallControl] is missing"}...
Then some of event filters are disabled due to some reason. You need to manual review them and either ignore them or take actions to enable them.
What is a validation token?
The Validation token is a unique token auto specified by the RingCentral server. When you try to setup the WebHook, the RingCentral server sends some sample 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.
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.
Please note that, by design, RingCentral server will only send you this validation token header when you try to setup the WebHook. After the WebHook is setup, there will be no such a header in event messages sent to your WebHook URI.
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!).
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.
Does RingCentral WebHook support retrying?
No, it doesn’t. And this is by design. So if your WebHook server is down when RingCentral tries to send it a notification, the notification will be lost. So you need to make sure that your server has high availability in order not to miss any important notifications. High availability is a big topic and it is out of the scope for this article. A popular way to achieve high availability is to build a High-availability Cluster.
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.
- 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.
- If everything seems fine on your side but RingCentral server complains about “WebHook URI not reachable”, it could be your local firewall issue. Please read this article https://support.ringcentral.com/article/9233.html?language=en_US and add “IP supernets” to your local firewall whitelist.
- 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 WebSocket?
WebHook isn’t the only way to get notifications, but RingCentral also supports WebSocket. WebHook and WebSocket can be substituted for each other.
A reason you might choose to use WebSocket over a WebHook is security or firewalls that prevent your URL from being publicly available.
If you are interesting in getting notifications via WebSocket, please read Create WebSocket subscriptions using RingCentral JavaScript SDKs.
Now that you have a better understanding of RingCentral WebHooks, it’s time to build your own!
WebHook IP address whitelist
If for some reason you don’t want your WebHook URI to be public, you can configure your firewall rules to only allow traffic from RingCentral. For RingCentral IP addresses please check the RingCentral supernets.
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.
