Webhook Notifications Quick Start

Last updated: 2021-12-05

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 "REST API App" under "What type of app are you creating?" Click "Next."
Under "Authentication" select "Password-based auth flow."
Under "Security" add the following permissions:
- WebhookSubscriptions
- SMS

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.

Download and edit a `.env` file

Follow the instructions found in our guide to running Developer Guide code samples. Or:

Download our env-template and save it as a file named .env.
Edit your newly downloaded .env file, setting its variables with the proper values for the app you created above.

Select your preferred language below.

Javascript

Install RingCentral JavaScript SDK

$ npm install ringcentral --save
$ npm install dotenv --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 using the contents below.

const RC = require('@ringcentral/sdk').SDK
var http = require('http');
require('dotenv').config();

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

var server = http.createServer(function(req, res) {
  if (req.method == 'POST') {
    if (req.url == "/webhook") {
      if (req.headers.hasOwnProperty("validation-token")) {
        res.setHeader('Content-type', 'application/json');
        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 RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({
    'username':  process.env.RC_USERNAME,
    'password':  process.env.RC_PASSWORD,
    'extension': process.env.RC_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 python-dotenv

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 using the contents below.

from ringcentral import SDK

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

rcsdk = SDK( os.environ.get('RC_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()

try:
  platform.login(os.environ.get('RC_USERNAME'),
                 os.environ.get('RC_EXTENSION'),
                 os.environ.get('RC_PASSWORD') )
except:
  sys.exit("Unable to authenticate to platform. Check credentials.")

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)
except Exception as e:
    print(f"An exception was thrown: {e}")
else:
    print(f'{res}')

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('Content-type', 'application/json')
                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 vlucas/phpdotenv

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 using the contents below.

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

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

$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
                                  $_ENV['RC_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();

if (isset($_REQUEST['webhookcallback'])){
    if (array_key_exists('HTTP_VALIDATION_TOKEN', $_SERVER)) {
       header("Content-type: application/json");
       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( $_ENV['RC_USERNAME'],
                      $_ENV['RC_EXTENSION'],
                      $_ENV['RC_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
{
    static RestClient rc;
    public static void main(String[] args) throws IOException, RestException
    {
        String DELIVERY_ADDRESS = "<https://xxxxxxxxx.ngrok.io>";
    rc = new RestClient( System.getenv("RC_CLIENT_ID"),
                 System.getenv("RC_CLIENT_SECRET"),
                 System.getenv("RC_SERVER_URL") );
    try {
        rc.authorize( System.getenv("RC_USERNAME"),
              System.getenv("RC_EXTENSION"),
              System.getenv("RC_PASSWORD") );
    } catch (RestException | IOException e) {
        e.printStackTrace();
    }
        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
    {
        static RestClient restClient;
        const string DELIVERY_ADDRESS = "<https://xxxxxxxx.ngrok.io/webhook>";

        static async Task Main(string[] args)
        {
            restClient = new RestClient(
                Environment.GetEnvironmentVariable("RC_CLIENT_ID"),
                Environment.GetEnvironmentVariable("RC_CLIENT_SECRET"),
                Environment.GetEnvironmentVariable("RC_SERVER_URL"));
            restClient.Authorize(
                Environment.GetEnvironmentVariable("RC_USERNAME"),
                Environment.GetEnvironmentVariable("RC_EXTENSION"),
                Environment.GetEnvironmentVariable("RC_PASSWORD")).Wait();
            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 dotenv
$ 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'
require 'dotenv/load'

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

$rc = RingCentral.new( ENV['RC_CLIENT_ID'],
                       ENV['RC_CLIENRT_SECRET'],
                       ENV['RC_SERVER_URL'] )

$rc.authorize( username: ENV['RC_USERNAME'],
               extension: ENV['RC_EXTENSION'],
               password: ENV['RC_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('Content-Type' => 'application/json')
    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

Download and edit a .env file

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

Download and edit a `.env` file