Webhook Notifications Quick Start

Last updated: 2020-10-16

Contributors

Welcome to the RingCentral Platform. RingCentral is the leading unified communications platform. From one system developers can integrate with, or build products around all the ways people communicate today: SMS, voice, fax, chat and meetings.

In this Quick Start, we are going to help you create a Webhook push notifications app using our Push Notifications API, which allows your application receiving notifications on instant SMS message events. Let's get started.

Create an App

The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create Notifications App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create Webhook App Show detailed instructions

Login or create an account if you have not done so already.
Go to Console/Apps and click 'Create App' button.
Select "API App for RingCentral Office" under "What type of app are you creating?"
Select "Other Non-UI" under "Where will you be calling the API from?"
Select "Only members of my organization/company" under "Who will be authorized to access your app?"
On the second page of the create app wizard, enter your app's name and description. Then select the following permissions:
- WebhookSubscriptions, SMS
We are using Password Flow authentication, so leave "OAuth Redirect URI" blank.

When you are done, you will be taken to the app's dashboard. Make note of the Client ID and Client Secret. We will be using those momentarily.

Select your preferred language below.

Javascript

Install RingCentral JavaScript SDK

$ npm install ringcentral --save

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhook" to the address then paste it into the DELIVERY_ADDRESS variable in the code below.

Create and Edit webhook-notification.js

Create a file called webhook-notification.js. Be sure to edit the variables in ALL CAPS with your app and user credentials. Be sure to also set the recipient's phone number.

var http = require('http');
const RingCentral = require('@ringcentral/sdk').SDK

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

DELIVERY_ADDRESS = '<https://xxxxxxxx.ngrok.io/webhook>'

PORT = 5000

var server = http.createServer(function(req, res) {
  if (req.method == 'POST') {
    if (req.url == "/webhook") {
      if (req.headers.hasOwnProperty("validation-token")) {
        res.setHeader('Validation-Token', req.headers['validation-token']);
        res.statusCode = 200;
        res.end();
      } else {
        var body = []
        req.on('data', function(chunk) {
          body.push(chunk);
        }).on('end', function() {
          body = Buffer.concat(body).toString();
          var jsonObj = JSON.parse(body)
          console.log(jsonObj.body);
        });
      }
    }
  } else {
    console.log("IGNORE OTHER METHODS")
  }
});
server.listen(PORT);

var rcsdk = new RingCentral({ server: RINGCENTRAL_SERVER, clientId: RINGCENTRAL_CLIENTID, clientSecret: RINGCENTRAL_CLIENTSECRET });

var platform = rcsdk.platform();
platform.login({ username: RINGCENTRAL_USERNAME, password: RINGCENTRAL_PASSWORD, extension: RINGCENTRAL_EXTENSION })

platform.on(platform.events.loginSuccess, function(e) {
  console.log("Login success")
  subscribe_for_notification()
});

async function subscribe_for_notification() {
  var params = {
    eventFilters: ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'],
    deliveryMode: {
      transportType: "WebHook",
      address: DELIVERY_ADDRESS
    }
  }
  try {
    var resp = await platform.post('/restapi/v1.0/subscription', params)
    var jsonObj = await resp.json()
    console.log(jsonObj.id)
    console.log("Ready to receive incoming SMS via WebHook.")
  } catch (e) {
    console.error(e.message);
    throw e;
  }
}

Run Your Code

You are almost done. Now run your script.

$ node webhook-notification.js

Python

Install RingCentral Python SDK

$ pip install ringcentral

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhookcallback" to the address then paste it into the DELIVERY_ADDRESS variable in the code below.

Note: Running the demo code requires Python 3.x

Create and Edit webhook-notification.py

Create a file called webhook-notification.py. Be sure to edit the variables in ALL CAPS with your app and user credentials.

from ringcentral import SDK

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

DELIVERY_ADDRESS= '<https://XXXXXXXX.ngrok.io/webhookcallback>'

rcsdk = SDK( RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_SERVER)
platform = rcsdk.platform()
platform.login(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD)

try:
    eventFilters = ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS']
    params = {
        "eventFilters" : eventFilters,
        "deliveryMode": {
            "transportType": 'WebHook',
            "address": DELIVERY_ADDRESS
        }
    }
    res = platform.post("/subscription", params)
    return res
except Exception as e:
    return e

Create and Edit webhook-server.py

Create a file called webhook-server.py.

from http.server import BaseHTTPRequestHandler, HTTPServer

class S(BaseHTTPRequestHandler):
    def do_POST(self):
        path = self.path
        if path == "/webhookcallback":
            validationToken = self.headers['Validation-Token']
            if validationToken is not None:
                self.send_response(200)
                self.send_header('Validation-Token', validationToken)
                return self.end_headers()
            else:
                content_len = int(self.headers.get('Content-Length'))
                payload = self.rfile.read(content_len)
                print (payload)
                return
        else:
            print ("Ignore this")


def run(server_class = HTTPServer, handler_class = S, port=5000):
    server_address = ('', port)
    httpd = server_class(server_address, handler_class)
    print ('Starting httpd...')
    httpd.serve_forever()

if __name__ == "__main__":
    from sys import argv

if len(argv) == 2:
    run(port=int(argv[1]))
else:
    run()

Run Your Code

You are almost done. Now run your script.

Open a terminal window and run the server code.

$ python3 webhook-server.py

Open another terminal window and run the app

$ python3 webhook-notification.py

Now you can send an SMS message to the extension's phone number to see how you'll receive the notification.

PHP

Install RingCentral PHP SDK

$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar require ringcentral/ringcentral-php

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhook-notification.php?webhookcallback" to the address then paste it into the $DELIVERY_ADDRESS variable in the code below.

Create and Edit webhook-notification.php

Create a file called webhook-notification.php. Be sure to edit the variables in ALL CAPS with your app and user credentials.

<?php
require('vendor/autoload.php');

$RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
$RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
$RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

$RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
$RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
$RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

$DELIVERY_ADDRESS='<https://xxxxxxxx.ngrok.io/webhook-notification.php?webhookcallback>'

$rcsdk = new RingCentral\SDK\SDK($RINGCENTRAL_CLIENTID, $RINGCENTRAL_CLIENTSECRET, $RINGCENTRAL_SERVER);
$platform = $rcsdk->platform();

if (isset($_REQUEST['webhookcallback'])){
    if (array_key_exists('HTTP_VALIDATION_TOKEN', $_SERVER)) {
        return header("Validation-Token: {$_SERVER['HTTP_VALIDATION_TOKEN']}");
    }else{
      $jsonStr = file_get_contents('php://input');
      $jsonObj = json_decode($jsonStr, TRUE);
      print_r($jsonObj['body']['subject']);
    }
}else{
    $platform->login($RINGCENTRAL_USERNAME, $RINGCENTRAL_EXTENSION, $RINGCENTRAL_PASSWORD);
    $params = array(
            'eventFilters' => array(
                '/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'
                ),
            'deliveryMode' => array(
                'transportType' => "WebHook",
                'address' => $DELIVERY_ADDRESS
            ));
    try {
          $apiResponse = $platform->post('/subscription', $params);
          print_r ("Response: " . $apiResponse->text());
    }catch (Exception $e){
          print_r ("Exception: " . $e->getMessage());
    }
}

Run Your Code

You are almost done. Now run your script.

Open a terminal window and start PHP server.

$ php -S localhost:5000

Open another terminal window and run the app

$ php webhook-notification.php

Now you can send an SMS message to the extension's phone number to see how you'll receive the notification.

Java

Create a Java project (using Eclipse IDE)

Create a new Java project
Select the Gradle Project wizard
Enter project name "WebHook"
Open the build.gradle file and add the RingCentral Java SDK to the project as shown below:

dependencies {
    // ...
    compile 'com.ringcentral:ringcentral:1.0.0-beta10'
}

Create a new Java Class

Select "File -> New -> Class" to create a new Java class named "SubscribeForWebHookNotification"

package SubscribeForWebHookNotification;

public class SubscribeForWebHookNotification {

  public static void main(String[] args) {
    // TODO Auto-generated method stub

  }
}

Edit the file "SubscribeForWebHookNotification.java".

Be sure to edit the variables in ALL CAPS with your app and user credentials. Be sure to also set the recipient's phone number.

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and paste it into the DELIVERY_ADDRESS variable in the code below.

package com.ringcentral;

import java.io.IOException;

import com.ringcentral.RestException;
import com.ringcentral.definitions.CreateSubscriptionRequest;
import com.ringcentral.definitions.NotificationDeliveryModeRequest;

public class SubscribeForWebHookNotification
{
    public static void main(String[] args) throws IOException, RestException
    {
        String RINGCENTRAL_CLIENTID = "<ENTER CLIENT ID>";
        String RINGCENTRAL_CLIENTSECRET = "<ENTER CLIENT SECRET>";
        String RINGCENTRAL_SERVER = "https://platform.devtest.ringcentral.com";

        String RINGCENTRAL_USERNAME = "<YOUR ACCOUNT PHONE NUMBER>";
        String RINGCENTRAL_PASSWORD = "<YOUR ACCOUNT PASSWORD>";
        String RINGCENTRAL_EXTENSION = "<YOUR EXTENSION";

        String DELIVERY_ADDRESS = "<https://xxxxxxxxx.ngrok.io>";

        RestClient rc = new RestClient(RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_SERVER_URL);
        rc.authorize(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD);
        var eventFilters = new String[] {"/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS"}
        CreateSubscriptionRequest createSubscriptionRequest = new CreateSubscriptionRequest()
                                                              .eventFilters(eventFilters)
                                                              .deliveryMode( new NotificationDeliveryModeRequest()
                                                                             .transportType("WebHook")
                                                                             .address(DELIVERY_ADDRESS)
                                                                             );
        var result = rc.restapi().subscription().post(createSubscriptionRequest);
        System.out.println(result.id);
        System.out.println("WebHook Ready");
        rc.revoke();
    }
}

Create a WebHookServer

We use Jetty embedded for our server. You can get it here.

Browse to the WebHook project folder and create a WebHookServer project

$ cd WebHook
$ curl -o jetty-all-uber.jar https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/9.4.19.v20190610/jetty-all-9.4.19.v20190610-uber.jar
$ touch WebhookServer.java
$ open WebhookServer.java

Edit the WebhookServer.java with code below:

package com.ringcentral;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.eclipse.jetty.server.Request;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.handler.AbstractHandler;

public class WebhookServer extends AbstractHandler
{
    @Override
    public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        response.setStatus(HttpServletResponse.SC_OK);
        response.setHeader("Validation-Token", request.getHeader("Validation-Token"));
        if(request.getMethod() == "POST")
        {
            String body = request.getReader().lines().collect(java.util.stream.Collectors.joining(System.lineSeparator()));
            System.out.println(body);
        }
        response.getWriter().println("OK");
        baseRequest.setHandled(true);
    }

    public static void main( String[] args ) throws Exception
    {
        Server server = new Server(5000);
        server.setHandler(new WebHookServer());
        server.start();
        server.join();
    }
}

Build and run the WebHook Server

$ mkdir classes
$ javac -d classes -cp jetty-all-uber.jar WebHookServer.java
$ java -cp classes:jetty-all-uber.jar com.ringcentral.WebHookServer

Now run the SubscribeForWebHookNotification app from Eclipse.

Send an sms to RINGCENTRAL_USERNAME phone number, and watch the output on the WebHookServer terminal window.

We use .NET core which is cross-platform. You can get it here.

Create a solution

mkdir webhook-demo
cd my-solution
dotnet new sln

Create WebHook Server project

cd webhook-demo
mkdir webhook-server
cd webhook-server
dotnet new web
cd ..
dotnet sln add ./webhook-server/webhook-server.csproj
cd webhook-server

Edit Startup.cs and override its content with code below:

using System;
using System.IO;
using System.Text;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Primitives;

namespace webhook_server
{
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment()) app.UseDeveloperExceptionPage();

        app.Run( async (context) =>
            {
                context.Request.Headers.TryGetValue("Validation-Token", out StringValues validationToken);
                context.Response.Headers.Add("Validation-Token", validationToken);
                if (context.Request.Path == "/webhook" && context.Request.Method == "POST")
                {
                    using (StreamReader reader = new StreamReader(context.Request.Body, Encoding.UTF8))
                    {
                        var str = reader.ReadToEnd();
                        Console.WriteLine(str);
                    }
                }
            });
    }
}
}

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhook" to the address then paste it into the DELIVERY_ADDRESS variable in the code below.

Create Setup WebHook project

cd my-solution
mkdir setup-webhook
cd setup-webhook
dotnet new console
cd ..
dotnet sln add ./setup-webhook/setup-webhook.csproj
cd setup-webhook
dotnet add package RingCentral.Net

Edit setup-webhook.csproj file and add <LangVersion>latest</LangVersion> to <PropertyGroup>.

Edit Program.cs file and override its content with code below. Be sure to edit the variables in with your app credentials.

using System;
using System.Threading.Tasks;
using RingCentral;

namespace setup_webhook
{
class Program
{
    const string RINGCENTRAL_CLIENT_ID = "<RINGCENTRAL_CLIENT_ID>";
    const string RINGCENTRAL_CLIENT_SECRET = "<RINGCENTRAL_CLIENT_SECRET>";
    const bool RINGCENTRAL_PRODUCTION = false;

    const string RINGCENTRAL_SERVER_URL = "https://platform.devtest.ringcentral.com";
    const string RINGCENTRAL_USERNAME = "<RINGCENTRAL_USERNAME>";
    const string RINGCENTRAL_EXTENSION = "<OPTIONAL>";
    const string RINGCENTRAL_PASSWORD = "<RINGCENTRAL_PASSWORD>";

    const string DELIVERY_ADDRESS = "<https://xxxxxxxx.ngrok.io/webhook>";

    static async Task Main(string[] args)
    {
        var rc = new RestClient(RINGCENTRAL_CLIENT_ID, RINGCENTRAL_CLIENT_SECRET, RINGCENTRAL_PRODUCTION);
        await rc.Authorize(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD);
        await rc.Restapi().Subscription().Post(new CreateSubscriptionRequest
            {
                eventFilters = new[] {"/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS"},
                deliveryMode = new NotificationDeliveryModeRequest
                {
                    transportType = "WebHook",
                    address = DELIVERY_ADDRESS
                }
            });
        Console.WriteLine("WebHook ready!");
    }
}
}

Run Your Code

You are almost done. Now run your script.

cd my-solution
cd webhook-server
dotnet run

Open a new terminal and run:

cd my-solution
cd setup-webhook
dotnet run

Test the app

Send an sms to RINGCENTRAL_USERNAME phone number, and watch the output of my-solution/webhook-server project.

Ruby

Install RingCentral Ruby SDK

$ gem install ringcentral-sdk
$ gem install sinatra

Run ngrok to create a localhost tunnel

$ ngrok http 5000

Copy the forwarding address e.g. https://54a0541a.ngrok.io and paste it into the DELIVERY_ADDRESS variable in the code below.

Create and Edit webhook-notification.rb

Create a file called webhook-notification.py. Be sure to edit the variables in ALL CAPS with your app and user credentials.

require 'ringcentral'

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

DELIVERY_ADDRESS= '<https://xxxxxxxx.ngrok.io>'


rc = RingCentral.new(RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_SERVER)
rc.authorize(username: RINGCENTRAL_USERNAME, extension: RINGCENTRAL_EXTENSION, password: RINGCENTRAL_PASSWORD)

r = rc.post('/restapi/v1.0/subscription', payload: {
    eventFilters: ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'],
    deliveryMode: { transportType: 'WebHook', address: DELIVERY_ADDRESS }
})

puts r.body['id']
puts "WebHook Ready"

rc.revoke()

Create and Edit webhook-server.rb

Create a file called webhook-server.rb.

require 'sinatra'
set :port, 5000
post '/' do
    status 200
    headers('Validation-Token' => request.env['HTTP_VALIDATION_TOKEN']) if request.env['HTTP_VALIDATION_TOKEN']
    request.body.rewind
    body = request.body.read
    puts body
    # do whatever with body
    body 'OK'
end

Run Your Code

You are almost done. Now run your script.

Open a terminal window and run the server code.

$ ruby webhook-server.rb

Open another terminal window and run the app

$ ruby webhook-notification.rb

Now you can send an SMS message to the extension's phone number to see how you'll receive the notification.

Graduate Your App

Congratulations on creating your first RingCentral application. The last step is to graduate your application. We recommend going through this process for your first application so you can understand the steps to take in the future, but also to come to appreciate the care taken by RingCentral to ensure that only high-quality apps are allowed into our production environment.

Webhook Notifications Quick Start

Create an App

Subscribe for push notification

Install RingCentral JavaScript SDK

Run ngrok to create a localhost tunnel

Create and Edit webhook-notification.js

Run Your Code

Install RingCentral Python SDK

Run ngrok to create a localhost tunnel

Create and Edit webhook-notification.py

Create and Edit webhook-server.py

Run Your Code

Install RingCentral PHP SDK

Run ngrok to create a localhost tunnel

Create and Edit webhook-notification.php

Run Your Code

Create a Java project (using Eclipse IDE)

Create a new Java Class

Edit the file "SubscribeForWebHookNotification.java".

Create a WebHookServer

Build and run the WebHook Server

Create a solution

Create WebHook Server project

Run ngrok to create a localhost tunnel

Create Setup WebHook project

Run Your Code

Test the app

Install RingCentral Ruby SDK

Run ngrok to create a localhost tunnel

Create and Edit webhook-notification.rb

Create and Edit webhook-server.rb

Run Your Code

Graduate Your App